Get SKAN Conversion Info API Reference (For Singular Partners)

Follow
Avatar
Dora Kishinevsky
Updated

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:

[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:

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:

  • PERIOD_0_Fine
  • PERIOD_0_Coarse
  • PERIOD_1_Coarse
  • PERIOD_2_Coarse

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:

  • 1 - HTTP 400, Invalid app ID in request.
  • 2 - HTTP 400, Partner is not configured for this app. The advertiser needs to configure the Partner Configuration for the partner in their Singular dashboard.
  • 3 - HTTP 200, Singular SKAdNetwork is not enabled for this app. The advertiser needs to enable SKAdNetwork measurement with Singular.

 
message

Description message corresponding to the status

  • status=1 - "Invalid App ID"
  • status=2 - "[Partner] is not configured for this app"
  • status=3 - "Singular SKAN is not enabled for this app"

 
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_type: Either "revenue", "retention", "engagement", "conversion_events", or "funnel". Use this field along with the value field and the conversion_name to translate the given conversion value (0-63) into metrics/KPIs. See Conversion Types and Values below for more information.
  • value: A number/object that should be interpreted based on the conversion_type. See Conversion Types and Values below.
  • conversion_name: the event name given by the advertiser, e.g., "My IAP."
  • partner_conversion_name: The event name given by the advertiser (when supported), e.g., "IAP." If the advertiser hasn't mapped the event to a partner name, this field is null or contains an empty string.
  

Conversion Types and Values

conversion_type Sample value Description
revenue 
{
  "min": 0,
  "max": 5
}
 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 
{
  "min": 0,
  "max": 24
}
 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 
{
  "min": 2,
  "max": 2
}
 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:

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:

  • 1 - HTTP 400, Invalid app ID in request
  • 2 - HTTP 400, Partner is not configured for this app. Advertiser needs to configure the Partner Configuration for partner in their Singular dashboard
  • 3 - HTTP 200, Singular SKAdNetwork is not enabled for this app. Advertiser needs to enable SKAdNetwork measurement with Singular as well as enable .

 
message

Description message corresponding to the status

  • status=1 - "Invalid App ID"
  • status=2 - "[Partner] is not configured for this app"
  • status=3 - "Singular SKAN is not enabled for this app"

 
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_type: Either "revenue", "retention", "engagement", "conversion_events", or "funnel". Use this field along with the value field and the conversion_name to translate the given conversion value (0-63) into metrics/KPIs. See Conversion Types and Values below for more information.
  • value: A number/object that should be interpreted based on the conversion_type. See Conversion Types and Values below.
  • conversion_name: the event name given by the advertiser, e.g., "My IAP."
  • partner_conversion_name: The event name given by the advertiser (when supported), e.g., "IAP." If the advertiser hasn't mapped the event to a partner name, this field is null or contains an empty string.
  

Conversion Types and Values

conversion_type Sample value Description
revenue 
{
  "min": 0,
  "max": 5
}
 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 
{
  "min": 0,
  "max": 24
}
 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 
{
  "min": 2,
  "max": 2
}
 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).