Post-Install Postback API

Introduction 

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

Contents:

• 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: Liftoff 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: Liftoff 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 Liftoff Direct 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 Liftoff event identifier. If this event was performed by a user driven to your app by a Liftoff 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 Liftoff.

Optional Parameters

These parameters are optional, but they are important for Liftoff 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 Liftoff. 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. Liftoff is agnostic as to the actual numbers used, but events should have values that have relative value to each other. Liftoff 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"
  ]
}