Conversion Event

conversion-event

Conversion Event

POST conversion_event

Record a mobile measurement conversion event.

This relates to the GET conversion_attribution endpoint.

Either Twitter, TAP or no attribution will be claimed in the response. The twitter_attribution node will always be present and have a value of null when there is no Twitter attribution (see the example response below). If TAP attribution is claimed a tpn_attribution node will be present and populated accordingly. Please refer to the TAP overview for more information.

There are several optional parameters available to set metadata associated with each conversion event. This metadata has no effect on attribution calculations.

Resource URL

https://ads-api.x.com/11/conversion_event

Parameters

Name Description
app_id
required

The unique identifier with the corresponding app store.

Type: int, string

Example: 333903271, com.vine.android

conversion_time
required

The time of the conversion event in an ISO-8601 timestamp format, with milliseconds appended.

Type: string

Example: 2014-05-22T02:38:28.103Z

conversion_type
required

The type of conversion event.

Type: enum

Possible values: PURCHASE, SIGN_UP, INSTALL, RE_ENGAGE, UPDATE, TUTORIAL_COMPLETE, RESERVATION, ADD_TO_CART, ADD_TO_WISHLIST, LOGIN, CHECKOUT_INITIATED, SEARCH, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, CONTENT_VIEW, SHARE, INVITE, ADDED_PAYMENT_INFO, SPENT_CREDITS, RATED

hashed_device_id
required

The HMAC_SHA-256 hashed IDFA or AdID.

Type: string

Example: ABCD1234XYZ

os_type
required

The OS type for the app.

Type: enum

Possible values: IOS, ANDROID

click_window
optional

The click window for this event in days.

Type: int

Note: click_window must be greater than or equal to view_through_window

Default: 14
Possible values: 1, 7, 14, 30
device_ip_address
optional

IPv4 or IPv6 address of the device when the conversion event happened.

Type: string

Example: 192.133.78.1

level
optional

A level associated with this event.

Type: int

Example: 2
non_twitter_engagement_time
optional

The time of the last non-twitter engagement prior to the conversion.

Type: string

Example: 2014-05-22T02:38:28.103Z

non_twitter_engagement_type
optional

The type of non-twitter engagement prior to the conversion event.

Type: enum

Possible values: CLICK, VIEW

number_items
optional

Number of items associated with this event.

Type: int

Example: 2
price_currency
optional

Expected to be an ISO 4217 code to indicate the currency associated with this event.

Type: String

Examples: EUR,USD,JPY
price_micro
optional

A price amount associated to this event in micro.

Type: int

Example: 123450000
user_payment_info
optional

A boolean value to indicate if the user’s payment information is stored in the app associated with this event.

Type: bool

Possible values: true or false
view_through_window
optional

The view through window for this event in days.

Note:

click_window must be greater than or equal to view_through_window.

 

Type: int

Default: 1
Possible values: 0, 1, 7, 14, 30

Example Request

https://ads-api.x.com/11/conversion_event?app_id=333903271&os_type=IOS&hashed_device_id=ABCD1234XYZ&conversion_type=INSTALL&conversion_time=2013-04-16T07:00:00.123Z&click_window=14&view_through_window=1

Example Response

{
  "data": {
    "conversion_value_micro": 0,
    "view_through_window": 1,
    "tpn_attribution": null,
    "conversion_time": "2017-01-21T01:14:00.602Z",
    "click_window": 30,
    "limit_ad_tracking": false,
    "event_metadata": null,
    "non_twitter_engagement_type": null,
    "conversion_type": "INSTALL",
    "partner_client_id": "com.appname contact id",
    "app_id": "com.appname",
    "hashed_device_id": "lke1GZa3AseB343ZcCQq7svfHzLfuSqyYnE+Rf49MOI=",
    "twitter_attribution": {
      "country_code": "US",
      "engagement_time": "2017-01-21T01:13:00.602Z",
      "engagement_type": "CLICK",
      "attribution_type": "PROMOTED",
      "promoted_properties": {
        "campaign_id": "4ns44",
        "line_item_id": "3x44d",
        "publisher_app_id": "333903271"
        "account_id":"18ce11e3egb",
        "line_item_objective": "APP_INSTALLS",
        "campaign_name": null
      },
      "tweet_id": "11434635565377600"
    },
    "os_type": "ANDROID",
    "non_twitter_engagement_time": null
  },
  "request": {
    "params": {
      "version_number": "1",
      "app_id": "com.appname",
      "conversion_type": "INSTALL",
      "os_type": "ANDROID",
      "hashed_device_id": "lke1GZa3AseB343ZcCQq7svfHzLfuSqyYnE+Rf49MOI=",
      "conversion_time": "2017-01-21T01:14:00.602Z",
      "click_window": "30",
      "view_through_window": "1",
      "limit_ad_tracking": "false"
    }
  }
}