If you are an ad network partnered with Singular, you can use the Conversion Model API to get the details of the current conversion model configured by an advertiser. NOTE: This is a limited feature. To access this API, contact your Singular partner manager or our Singular Support.
For more information, see Integrating with Singular SKAdNetwork: FAQ for Partners.
If you're a Singular customer, see the Model Configuration FAQ instead.
Get SKAN Conversion Info Endpoint
GET | https://api.singular.net/api/skadnetwork/conversion_info |
Usage
SKAdNetwork postbacks can contain a conversion value, which is a number between 0 and 63. Singular offers a choice of several different "conversion models" to map as much information as possible into the conversion value. Advertisers can adjust a conversion model's settings or switch to a different conversion model on the fly through the conversion model dashboard.
If you want to parse the conversion value, query the conversion model endpoint to get the full details of the conversion model currently enabled for an app.
This API will return the configured conversion model for a given app(s), provided the following requirements have been met:
- The advertiser app has an active configured Conversion Model.
- The advertiser has an active Partner Configuration created for the partner.
- Partner has access to the Partner Portal to retrieve an API Key.
Sample Query
https://api.singular.net/api/skadnetwork/conversion_info?api_key=[api_key]&app_id=14
41750662&org_type=partner
Query Parameters
Parameter | Required? |
Description | Example |
api_key | Yes |
The Singular SKAN API key provided by Singular for the SKAdNetwork integration. Can either be part of the URL, or the Authorization HTTP header. |
6aed7434-737f-4cae-9fd4-ff 1a0f17b0d1 |
app_id | Yes | The Apple App ID. | 1441750662 |
bundle_id | Yes | The app's bundle ID (required if the app is not live in the App Store yet). | com.my.app |
org_type | org_type | Enter "partner". | partner |
app_response_type | No | Default is "bundle_id". Identify if the API response should be keyed by an app's bundle ID or Apple App ID. Note that app_response_type=app_id will only return apps live in the app store. app_response_type=bundle_id includes apps not yet live in the app store. | app_id bundle_id |
Sample Response
{
"com.my.app": {
"currency": "USD",
"keepalive_interval": 24,
"measurement_period": 168,
"start_ts": 1601856000,
"update_ts": 1601856000,
"version": 5,
"previous_version": 4,
"conversion_model": {
"0": [
{
"conversion_name": "purchase",
"conversion_type": "conversion_events",
"partner_conversion_name": "Partner Purchase",
"value": 0
},
{
"conversion_name": "Add To Cart",
"conversion_type": "conversion_events",
"partner_conversion_name": "Partner Add to Cart",
"value": 0
},
{
"conversion_name": "retention",
"conversion_type": "retention",
"partner_conversion_name": "Partner App Open",
"value": {"min": 0,"max": 24}
}
],
"1": [
{
"conversion_name": "purchase",
"conversion_type": "conversion_events",
"partner_conversion_name": "Partner Purchase",
"value": 0
},
{
"conversion_name": "Add To Cart",
"conversion_type": "conversion_events",
"partner_conversion_name": "Partner Add to Cart",
"value": 1
},
{
"conversion_name": "retention",
"conversion_type": "retention",
"partner_conversion_name": "Partner App Open",
"value": {"min": 0,"max": 24 }
}
],
"2": [
{
"conversion_name": "purchase",
"conversion_type": "conversion_events",
"partner_conversion_name": "Partner Purchase",
"value": 1
},
{
"conversion_name": "Add To Cart",
"conversion_type": "conversion_events",
"partner_conversion_name": "Partner Add to Cart",
"value": 1
},
{
"conversion_name": "retention",
"conversion_type": "retention",
"partner_conversion_name": "Partner App Open",
"value": {"min": 0, "max": 24 }
}
]
}
}
}
Response Fields
Field | Description |
bundle_id object | One or more of these are returned if the request was successful. Each bundle ID contains the details of the conversion model configured for the respective app. |
status |
Integer returned if there is an error:
|
message |
Description message corresponding to the status
|
Bundle_id Object Fields
Field | Description | Example |
start_ts | Timestamp of when this model was activated (Unix format) | 1601856000 |
update_ts | Timestamp of when this model was last updated | 1601856000 |
version | The version number of the conversion model | 2 |
previous_version | The previous version number of the conversion model | 1 |
measurement_period | The maximum period, in hours, that the conversion model uses to track post-install events. Singular supports up to 7 days (168 hours). | 168 |
keepalive_interval | The time interval, in hours, that the conversion model uses to implement "keep-alives" for conversion value tracking. Singular currently supports 24-hour intervals. | 24 |
currency | The currency set for the advertiser's Singular account. Any revenue details appearing in the response are based on this currency. | USD |
conversion_model |
An object containing a list of possible conversion values. Each value contains an array of detail objects that together describe the meaning of the conversion values. Note that the list does not necessarily contain every number from 0 to 63, as some values may be unused by the conversion model.
|
Conversion Types and Values
conversion_type | Sample value | Description |
revenue |
|
If you see this conversion type, it means the advertiser has chosen to focus on revenue gained from the end-user within the limits of the measurement period. Due to the limitations of the conversion value, revenue isn't given as an exact number but as a category or "bucket" of revenue. In this example, the revenue from the end-user is between 0-5 (in the currency defined for the account - see bundle_id.currency). |
retention |
|
This conversion type means that the advertiser has chosen to track the approximate time after the install in which this conversion event occurred. The time is given as one of several "buckets" defined by the customer, with a lower bound ("min") and a higher bound ("max"), in hours. |
engagement |
|
This conversion type means the advertiser chose to track how many instances of the event have occurred within the measurement period (the event is denoted by the conversion_name and the partner_conversion_name). |
conversion_events | 1 | This conversion type means the advertiser has chosen to track if the event has occurred at least once within the measurement period. 0 means that the event hasn't occurred, and 1 means that it has occurred (the event is denoted by the conversion_name and the partner_conversion_name). |
funnel | 1 | This conversion type means the advertiser chosen to track if the event has occurred at least once within the measurement period. 0 means that the event hasn't occurred, and 1 means that it has occurred (the event is denoted by the conversion_name and the partner_conversion_name). |