Overview
SKAdNetwork enabled partners must hit Branch's Conversion Value Mapping Partner API in order to fetch mutual customer value mappings with multiple conversion windows.
Endpoint
Partners should use the following endpoint for Branch's Conversion Value Mapping Partner API:
https://api2.branch.io/v3/partners/<partner_3P>/conversion-value-mappings?app_id=<iTunesId>Please note that the /v3/partners/ endpoint will work for SKAN 4.0 as well as SKAN 3.0 and below.
Authentication
Send an access token with each request in the Authorization: Bearer <access_token> header. To get a token, see Generate JWT Access Token.
Schema
When making a request to Branch's Partner API, the following schema should be used:
{
"app-id": <iTunesId> ,
"update": "<yyyy-mm-dd hh:mm:ss.sss>",
"mapping": {
"postback-sequence-index-0": [{
"conversion-value": "<0-63 or low, medium, high>",
"conversion-event": [{
"values": {
"name": [
"eq",
"<event_name>"
]
},
"locked": <true/false>
}]
},
{
"conversion-value": "<0-63 or low, medium, high>",
"conversion-event": [{
"values": {
"name": [
"eq",
"<event_name>"
],
"event_data.revenue": [
"between",
<number>,
<number>
]
},
"locked": <true/false>
}]
}
],
"postback-sequence-index-1": [{
"conversion-value": "<low, medium, high>",
"conversion-event": [{
"values": {
"name": [
"eq",
"<event_name>"
]
},
"locked": <true/false>
}]
},
{
"conversion-value": "<low, medium, high>",
"conversion-event": [{
"values": {
"name": [
"eq",
"<event_name>"
],
"event_data.revenue": [
"between",
<number>,
<number>
]
},
"locked": <true/false>
}]
}
],
"postback-sequence-index-2": [{
"conversion-value": "<low, medium, high>",
"conversion-event": [{
"values": {
"name": [
"eq",
"<event_name>"
]
},
"locked": <true/false>
}]
},
{
"conversion-value": "<low, medium, high>",
"conversion-event": [{
"values": {
"name": [
"eq",
"<event_name>"
],
"event_data.revenue": [
"between",
<number>,
<number>
]
},
"locked": <true/false>
}]
}
]
}
}Conversion event conditions
Each entry in conversion-event has a values object. Each key in values is a field, and its value is an array: an operator first, then its operands.
Branch returns these conditions as they're configured in the advertiser's conversion value mapping. The only change Branch makes is to the event name. If the advertiser has mapped a Branch event to one of your events in their partner settings, name contains your event name. Otherwise, it contains the Branch event name.
Fields you may see
The values object can contain the following fields:
| Field | Format | Description |
|---|---|---|
name | ["eq", | The event that triggers this conversion value. |
event_data. | ["between", | Revenue range for the event. |
event_data. | ["lte", | Revenue less than or equal to the upper bound. Used when the range starts at 0. |
customer_event_alias | ["eq", | Optional customer event alias. The value can be null. |
Notes
- Revenue bounds are numbers and can be decimals (for example
0.01or13.5), not just integers. - When an advertiser sets a revenue range starting at 0 in Branch, it's saved as
ltewith the upper bound instead ofbetween. For example, Branch returns a $0 to $0.01 range as["lte", 0.01]. - Adjacent revenue ranges can share a boundary value (for example
["lte", 4]followed by["between", 4, 100000]).
Revenue range example
The following entry maps Purchase events with $0 to $0.01 in revenue to conversion value 1:
{
"conversion-value": "1",
"conversion-event": [{
"values": {
"name": ["eq", "Purchase"],
"event_data.revenue": ["lte", 0.01]
},
"locked": false
}]
}Full mapping example
The following is an example of a well-formatted request made to the Branch Partner API:
{
"app-id": 1667996582,
"update": "2023-09-26 16:04:34.607",
"mapping": {
"postback-sequence-index-0": [{
"conversion-value": "0",
"conversion-event": [{
"values": {
"name": [
"eq",
"MOBILE_APP_INSTALL"
]
},
"locked": false
}]
},
{
"conversion-value": "1",
"conversion-event": [{
"values": {
"name": [
"eq",
"StartTrial"
]
},
"locked": true
}]
},
{
"conversion-value": "2",
"conversion-event": [{
"values": {
"name": [
"eq",
"StartTrial"
]
},
"locked": true
}]
},
{
"conversion-value": "3",
"conversion-event": [{
"values": {
"name": [
"eq",
"fb_mobile_purchase"
],
"event_data.revenue": [
"between",
0,
100
]
},
"locked": true
}]
},
{
"conversion-value": "low",
"conversion-event": [{
"values": {
"name": [
"eq",
"MOBILE_APP_INSTALL"
]
},
"locked": false
}]
},
{
"conversion-value": "high",
"conversion-event": [{
"values": {
"name": [
"eq",
"StartTrial"
]
},
"locked": true
},
{
"values": {
"name": [
"eq",
"StartTrial"
]
},
"locked": true
},
{
"values": {
"name": [
"eq",
"fb_mobile_purchase"
],
"event_data.revenue": [
"between",
0,
100
]
},
"locked": true
}
]
}
],
"postback-sequence-index-1": [{
"conversion-value": "low",
"conversion-event": [{
"values": {
"name": [
"eq",
"MOBILE_APP_INSTALL"
]
},
"locked": false
}]
},
{
"conversion-value": "high",
"conversion-event": [{
"values": {
"name": [
"eq",
"StartTrial"
]
},
"locked": true
},
{
"values": {
"name": [
"eq",
"StartTrial"
]
},
"locked": true
},
{
"values": {
"name": [
"eq",
"fb_mobile_purchase"
],
"event_data.revenue": [
"between",
0,
100
]
},
"locked": true
}
]
}
],
"postback-sequence-index-2": [{
"conversion-value": "low",
"conversion-event": [{
"values": {
"name": [
"eq",
"MOBILE_APP_INSTALL"
]
},
"locked": false
}]
},
{
"conversion-value": "high",
"conversion-event": [{
"values": {
"name": [
"eq",
"StartTrial"
]
},
"locked": true
},
{
"values": {
"name": [
"eq",
"StartTrial"
]
},
"locked": true
},
{
"values": {
"name": [
"eq",
"fb_mobile_purchase"
],
"event_data.revenue": [
"between",
0,
100
]
},
"locked": true
}
]
}
]
},
"ascending-only": true
}