Post-Install Postback API Documentation

Julia Randall

July 16, 2021 15:22

Introduction

This endpoint enables advertisers to send Vungle data about each user-level event as it happens. The purpose of the event data API is for advertisers to help Vungle learn which users are valuable to you. When you send us event information within your app, Vungle can optimize your campaigns to help you get the users who matter to you.

HTTPS Request
Required Parameters
Optional Parameters
Error Codes

HTTPS Request

https://ingest.vungle.com/eventData

POST

We support POST requests with the following body content-types:

application/x-www-form-urlencoded
application/json

Note: Vungle recommends using the POST method with a JSON body.

curl -H "Content-Type: application/json" -d '{"data": "myData"}' "https://ingest.vungle.com/eventData"

GET

We also support GET requests using query parameters.

curl "https://ingest.vungle.com/eventData?data=myData"

Required Parameters

Each event that you send us has both required and optional parameters. We’ll reject any requests that don’t have the necessary parameters, and we’ll tell you which ones are missing. See the errors section for more details.

Device Identifier

We require at least ONE device identifier per event, so you don’t need to pass them all.

Parameter	Description
`device_idfa`	Apple IDFA or Google Play Services Advertising ID
`device_mac`	Mac Address in canonical format, either hyphen or colon separated
`device_other_id`	Some other unique identifier, e.g. Android ID, hashed identifiers, etc.

Note: Vungle recommends using device_idfa wherever possible!

Other Required Parameters

You need to pass all of the remaining required parameters for us to accept the event.

Parameter	Description
`vungle_app_id`	App ID as given on the Vungle dashboard
`trk`	Source of the incoming event. In the case of a direct server to server integration, you should self-identifier, else you should identify the tracking provider, e.g. ‘tune’, 'kochava’,'adjust’,'appsflyer’,etc.
`event_trk_id`	This should be an identifier that is unique to the event. Used for deduplication.
`event_id`	The Vungle event identifier. If this event was performed by a user driven to your app by a Vungle campaign, this event identifier was passed to you in the view or click tracker
`event_name`	This should be a string that identifies the event that is consistent across users, e.g. 'tutorial-complete’, 'level-3’, 'purchase' etc.

Examples

An example POST body:

{
  "device_idfa"   : "236A005B-700F-4889-B9CE-99",
  "vungle_app_id" : "myVungleApp",
  "trk"           : "tune",
  "event_trk_id"  : "uniqueID1234",
  "event_name"    : "tutorial-complete"
}

An example GET request:

curl "https://ingest.vungle.com/eventData?device_idfa=236A005B-700F-4889-B9CE-999EAB2B605D&vungle_app_id=myVungleApp&trk=tune&event_trk_id=uniqueID1234&event_name=tutorial-complete"

The above payloads would return a '200 OK' response, and are examples of the minimum request you can send to Vungle.

Optional Parameters

These parameters are optional, but they are important for Vungle to determine which are the users of value, so you should pass as many of them as possible.

Parameter	Default	Description
event_value	None	Some numerical value associated with the event. Should be relative to other events that you send to Vungle. For example, a $4.99 IAP should be 4.99.
`event_currency`	`'usd'`	If `event_value` is an explicit monetary value, define the currency here.
`event_iap_event`	`false`	Set a flag here to state whether the event was an in-app purchase.
`device_limit_track`	`false`	Boolean for whether device has 'limit ad tracking’ set.
`event_datetime`	Timestamp of event reception	Timestamp of event occurrence. If timezone not specified, UTC assumed. Timestamp should be in ISO 8601 format.
`device_ip`	None	IP address of device.
`device_make`	None	Device manufacturer.
`device_model`	None	Device model.
`device_carrier`	None	Device cell carrier.
`device_language`	None	ISO 639-1 language code of device (2 digits).
`device_country`	None	ISO 3166 country code of source IP (2 digits).
`device_user_agent`	None	Device’s browser user agent.
`device_os`	None	Operating system version number.

Note: Be sure to take note of the event_value parameter, and consider the values of each event. Vungle is agnostic as to the actual numbers used, but events should have values that have relative value to each other. Vungle will seek to maximize the overall value of the types of users we send you.

Example Optional Parameters

{
  "event_currency"      : "usd",
  "event_iap_event"     : true,
  "device_limit_track"  : false,
  "event_datetime"      : "2015-03-15T13:27:36Z",
  "device_ip"           : "201.15.25.11",
  "device_make"         : "samsung",
  "device_model"        : "sm-g900v",
  "device_carrier"      : "verizon",
  "device_language"     : "es",
  "device_country"      : "us",
  "device_user_agent"   : "Mozilla/5.0 (Linux; U; Android 2.2.1; fr-fr; HTC_DesireZ_A7272 Build/FRG83D) AppleWebKit/533.1 (KHTML, like Gecko), Version/4.0 Mobile Safari/533.1",
  "device_os"           : "4.3.2",
  "event_value"         : 1.99
}

Error Codes

We return the following codes:

Error Code	Meaning
`200`	OK
`400`	Bad Request – Most likely you’ve omitted one of the required parameters. Check the response body for clues.
`500`	Internal Server Error – We had a problem with our server. Try again later.
`503`	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

If we respond with a '400 BAD REQUEST', then check the response body. We’ll do our best to diagnose what’s wrong, which is most likely going to be a missing field or two. For example,

curl "https://ingest.vungle.com/eventData?trk=tune&event_trk_id=uniqueID1234"

Would return a response that looks like this:

{
  "missing_fields":
  [
    "vungle_app_id",
    "trk",
    "event_trk_id",
    "event_name",
    "device_idfa | device_mac | device_other_id"
  ]
}