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.
Notes:
- May 2023 Update: We now offer a new, separate endpoint to get SKAN 4.0 conversion info (learn more about SKAdNetwork 4.0 in the FAQ for Partners). The original conversion API endpoint is still available for SKAN 3.0.
- This is a limited feature. To access this API, contact your Singular partner manager or our Singular Support.
- If you're a Singular customer, see the Model Configuration FAQ instead.
[NEW] SKAN 4.0 Get Conversion Info Endpoint
GET | https://api.singular.net/api/skadnetwork/v2/conversion_info |
Usage
SKAdNetwork 4.0 postbacks can contain a fine conversion value (a number between 0 and 63) or a coarse conversion value (whose possible values are "low", "medium", and "high"). These conversion values can be used to encode information about the install and about the user's post-install activities.
Singular offers its customers 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.
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/v2/conversion_info?api_key=[api_key]&app_id=[app_id]&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 |
identify if the API response should be keyed by an app's bundle ID or Apple App ID. Default: bundle_ud Note that app_response_type=app_id 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.example.app":{
"period_0_fine":{
"update_ts":...,
"currency":"USD",
"version":...,
"encoding_start_time":...,
"measurement_period":24,
"conversion_model":{
......
"20":[
{
"conversion_type":"retention",
"partner_conversion_name":null,
"conversion_name":"retention",
"value":{"max":24,"min":0}
}
],
"21":[
{
"conversion_type":"retention",
"partner_conversion_name":null,
"conversion_name":"retention",
"value":{"max":24,"min":0}
},
{
"conversion_type":"funnel",
"partner_conversion_name":null,
"conversion_name":"__iap__",
"value":1
}
],
.........
}
},
"period_0_coarse":{
"update_ts":1684165181,
"currency":"USD",
"version":28,
"encoding_start_time":1684337981,
"measurement_period":48,
"conversion_model":{
"high":[
[
{
"conversion_type":"retention",
"partner_conversion_name":null,
"conversion_name":"retention",
"value":{"max":24,"min":0
}
},
{
"conversion_type":"funnel",
"partner_conversion_name":null,
"conversion_name":"__iap__",
"value":1
}
]
],
"medium":[
......
],
"low":[
......
]
}
},
"period_1_coarse":{
"update_ts":...,
"currency":"USD",
"version":...,
"encoding_start_time":...,
"measurement_period":...,
"conversion_model":{
"high":[
{
"conversion_type":"combined_revenue",
"partner_conversion_name":...,
"conversion_name":"__REVENUE__",
"value":{"max":10.0,"min":1.0}
}
],
"medium":[
......
],
"low":[
......
]
}
}
"period_2_coarse":{
"update_ts":...,
"currency":"USD",
"version":...,
"encoding_start_time":...,
"measurement_period":...,
"conversion_model":{
"high":[
{
"conversion_type":"combined_revenue",
"partner_conversion_name":...,
"conversion_name":"__REVENUE__",
"value":{
"max":15.0,
"min":5.0
}
}
],
"medium":[
.......
],
"low":[
......
]
}
},
}
}
Response Fields
Field | Description | Example |
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. The object contains information on all the postbacks configured for the app. There are three postback in total, where the first postback can include either a fine or a coarse conversion value. In this response object, the postbacks are represented as:
Note: If the advertiser is using conversion models for SKAN 3 and below, the response will only include PERIOD_0_Fine. If the advertiser is using SKAN 4.0+ conversion models, the response may include PERIOD_0_Coarse, PERIOD_1_Coarse, and PERIOD_2_Coarse. |
|
status |
Integer returned if there is an error:
|
|
message |
Description message corresponding to the status
|
|
Bundle_id Object Fields | ||
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). |
SKAN 3.0 Get 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 | Example |
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 | ||
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). |