SKAN integration guide for ad networks

At a glance: Ad networks integrate with AppsFlyer SKAdNetworks (SKAN), enabling them to optimize campaigns and to be attributed to the traffic they generate.

SKAdPartnerBadges.png

Learn more about the AppsFlyer SKAN solution for advertisers:

SKAN solution guide | SKAN dashboard 

AppsFlyer可为广告平台提供:

  • 广告系列转化归因:
    • 和AppsFlyer进行对接可以确保广告主在该广告平台进行的营销活动里产生的所有应用安装,应用内事件,以及收益都可以被准确归因
    • 如果没有准确对接,上述提到的安装,应用内事件及收益都将会被算作自然量,无法归因给对应广告平台 
  • 广告系列优化:
    • 回调中所带的转化值是被编译过的
    • AppsFlyer可以让广告平台对于每条回调里的转化值进行转换,以此确保广告平台可以基于转化值传达的信息来优化广告系列
  • No need for direct integration with each advertiser:
    SKAN postbacks are sent only to the ad network. Advertisers can consume the data by either: 
    • 以独立身份对接每一个合作的广告平台,这种对接方式从广告主和广告平台来看都不是一种规模化方式 
    • 与AppsFlyer进行对接,这是对于广告主以及广告平台都相对提高效率的对接方式
  • 让您的渠道在AppsFlyer脱颖而出: 
    • Ad networks having SKAN integration are certified and identified as such in the AppsFlyer dashboard. 
    • 确保希望使用SKAdNetwork的广告主准确的找到支持此归因方式的广告平台

SKAN data flow

PostbackProcess_us-en.png

The full SKAN postback flow is as follows:

  1. iOS sends the SKAN postback to the attributed ad network.
  2. 广告平台可选择下列两种方式的的任意一种:
    • Enrich and forward: Enrich the SKAN postback with the ad network campaign ID (to overcome the SKAN limitation of 100 campaign IDs), campaign name, and the iOS device IP address. 
    • 重定向: 广告平台让iOS直接将回调重定向发送给AppsFlyer。在这种情形下,广告系列数据的维度补充会通过AppsFlyer以及广告平台间一个单独的API来进行
  3. AppsFlyer会对回调进行验证和反编译然后将包含更为详尽信息的回调发回给广告平台(并同时同步给广告主)

主要对接步骤

SKAN integration between AppsFlyer and ad networks consists of the following main parts as described in this article:

  • Ad networks send SKAN data to AppsFlyer
  • 广告平台通过AppsFlyer发回的回调收到转化值解码后更为丰富详细的数据

向AppsFlyer发送数据

After the ad network receives the SKAN postback from the device, the ad network forwards it to AppsFlyer using one of the following methods:

  • 补充数据维度并转发(POST)
  • 重定向(HTTP307重定向方式)

Upon receipt of a SKAN postback, AppsFlyer performs the following:

  • Postback validation: Ensure that it is unique.
  • 对转化值进行解码:生成归因激活及应用内事件记录。
  • 将解码后的回传发送到广告平台。
  • 通过数据面板和报告将归因数据提供给广告主和广告平台。

补充数据维度并转发

使用此方法,广告平台将从设备收到的每个回调转发到AppsFlyer。

广告平台

  • 接收来自iOS设备的回调
  • [Mandatory] Enriches the postback with:
    • 广告平台广告系列ID和广告系列名称
    • 从设备收到的IP地址,主要用于地理位置解析。
    • 从iOS设备发送的回调时间戳
  • [Optional] Enrich the postback with:
    • Adset ID and name
    • Ad ID and name
  • 再发送回调到AppsFlyer
  • Note! Before sending the postback to AppsFlyer, validate the Apple attribution signature using the content of the outgoing postback to ensure that you didn't inadvertently corrupt the data. 
SKAN enriched postback protocol
接口

https://skadpostbacks.appsflyer.com

HTTP方法 POST
可接收的格式 application/json
返回码

200 OK: Postback received has a valid format. 

400: Bad request: Malformed JSON, empty, JSON, missing mandatory fields.

SKAN enriched postback JSON parameters

参数

格式

描述

来源

version 字符串

SKAdNetwork 版本

举例: "version":"2.0"

SKAN postback
ad-network-id 字符串

广告平台 ID

Example: "ad-network-id":" abc123defg.SKAdnetwork"

SKAN postback
campaign-id Integer

SKAdNetwork 广告系列 ID

举例: "campaign-id":23

SKAN postback
transaction-id 字符串

SKAdNetwork 回传 transaction ID

SKAN postback
app-id Integer 目标t App ID SKAN postback
attribution-signature 字符串 归因签名 SKAN postback 
redownload 布尔 当 redownload = true, 意味用户从应用商店再次下载App SKAN postback
source-app-id Integer

流量源 App ID (开发者)

SKAN postback
conversion-value Integer

AppsFlyer SDK 根据广告主的配置设置的转化值

Notes!

  • iOS due to iOS privacy-preserving thresholds may not populate the parameter in the postback and the value will be null.
  • Null and 0 have different meanings:
    • Null: iOS withheld the conversion value
    • 0: The user installed the app but didn't perform any measured actions.  
SKAN postback 
ad-network-campaign-id 字符串

为了确保广告主,广告平台和AppsFlyer之间语言一直,请您务必提供给您的广告系列 ID

广告平台
ad-network-campaign-name 字符串 这一名称将显示在数据面板和数据报告中与广告系列匹配的广告系列名称。 广告平台
ad-network-adset-id 字符串

广告组ID

广告平台
ad-network-adset-name 字符串

广告组名称

广告平台
ad-network-ad-name 字符串

广告创意名称

广告平台
ad-network-ad-id 字符串

广告创意ID

广告平台
ip 字符串

这台发送回传的设备的IP地址

支持iPv4 及 IPv6 地址

举例: "ip":"198.51.100.1"

广告平台
时间戳 字符串

Time the ad network received the SKAN postback. A 10-digit epoch UNIX timestamp. [Optional] 13-digit epoch timestamp permitted.

示例:

August 4, 2020, 07:25 UTC translates  to "timestamp": "1596525944"

广告平台
fidelity-type Integer

Differentiate between ad presentation options that affect attribution. Indicated using the values 0 and1 as follows: 

  • View-though ads (0)
  • Storekit-rendered ads (1)

Mandatory field starting SKAN V2.2

SKAN postback (V2.2+)
did-win 布尔

Used to distinguish between campaigns contributing or attributed with the install. 

  • If true, the campaign is attributed for bringing the install.
  • If false, the campaign is recognized as contributing to the install
SKAN postback (V3.0+)
ad-network-source-app-id 字符串

Populate with the publisher ID that you associate with the app publishing the ad. This is usually the ID you allocated to the publisher, and not the ID generated by Apple. 

广告平台
ad-network-country-code 字符串

The user location (geo) as derived by the ad network.

Populate using ISO 3166 (alpha-2) codes.

Example: CN, ZA

Ad networks often derive geo according to a given campaign's target region.  

AppsFlyer uses the country code to populate geo-related fields in reports and dashboards. 

广告平台

 Ad network optional parameters sent via query params

参数

格式

描述

来源

ad_network_name

字符串

Name of the ad network

Example: ad_network_name=your_network

广告平台

app_id

字符串

The app id as it appears in AppsFlyer. Always has the prefix id.

Example:app_id=id123456789

广告平台

ad-network-country-code 字符串

The user location (geo) as derived by the ad network.

Populate using ISO 3166 (alpha-2) codes.

Example: CN, ZA

Ad networks often derive geo according to a given campaign's target region.  

AppsFlyer uses the country code to populate geo-related fields in reports and dashboards. 

广告平台

Curl example—enriched SKAN postback with optional query params

curl --location --request POST 'https://skadpostbacks.appsflyer.com/api/postbacks?app_id=id888707074' \
  --header 'Content-type: application/json' \
  --data-raw '{
      "version":"2.0",
      "app-id": 888707086,
      "ip": "192.0.2.0",
      "ad-network-campaign-name": "skadnetwork_abc_campaign",
      "source-app-id": 888707074,
      "ad-network-id": "abcabcabc.skadnetwork",
      "transaction-id": "68eb3d91-15f5-44ee-9267-25c7655c20b6",
      "redownload": false,
      "attribution-signature": "MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
      "timestamp": "1596525944",
      "ad-network-campaign-id": "222222",
      "conversion-value": 63,
      "campaign-id": 99
  }'

重定向

Redirect_us-en__2_.png

使用此方法,广告平台使用HTTP重定向命令来307来回应iOS设备发出的SKAdNetwork信息,请求设备将SKAdNetwork回调直接发送到AppsFlyer。 

重定向方法具有以下优点

  • 增加广告主的信任度:MMP代表广告主执行。通过向AppsFlyer提供一手回传信息,广告主可以确信,该回传在传输过程中不会受到操纵。
  • 广告平台无需做其他处理:广告平台(向设备)使用重定向指令,因此无需处理回传。相比之下,广告平台进行数据补充并转发的方法要求广告平台对回调进行处理,填充进其他参数,然后再将其转发给AppsFlyer

实现

  1. Configure your server to respond with an HTTP 307 response redirecting the postback to https://skadnetworkredirect.appsflyer.com/api/redirects
  2. Append query params that contain campaign details using the query params listed in the table that follows. Regard the sending of your campaign details as mandatory. Campaign details enable us to enrich SKAN data with cost and other campaign data and enable advertisers to effectively optimize campaigns.

重定向的SKAdNetwork请求举例

https://skadnetworkredirect.appsflyer.com/api/redirects?
  &ad-network-campaign-id=243232&ad-network-campaign-name=yarg_campaign_name
  &ad-network-adset-name=dsdsa

请求参数

描述

ad-network-campaign-id 广告系列活动ID
ad-network-campaign-name Campaign 名称
ad-network-adset-id 广告组ID
ad-network-adset-name 广告设置名称
ad-network-ad-id 广告ID
ad-network-ad-name 广告名称
ad-network-country-code

The user location (geo) derived by the ad network.

Populate using ISO 3166 (alpha-2) codes.

Example: CN, ZA

Ad networks often derive geo according to a given campaign's target region.  

AppsFlyer uses the country code to populate geo-related fields in reports and dashboards. 

建议添加的与广告系列相关的参数(非必须)

 

接收 AppsFlyer 传输数据

在收到第一次回调之前,请考虑以下因素: 

  • 广告平台必须定义回发端点和模板,请与您的AppsFlyer合作伙伴开发经理联系,或与邮件integrations@appsflyer.com 联络以确保已完成
  • AppsFlyer sends SKAN postbacks using the same mechanism as with the existing postbacks sent to you.

原则

  • 对于从广告平台发送到 AppsFlyer 的每个回调,AppsFlyer 都会发送:
    • 一个激活回。重新下载由 redownload 参数表示
    • 零到几次应用内事件回发确切的数字取决于转换值的请参阅模拟的回调
  • 当您使用回调时,同一激活或事件可以被多个AppsFlyer 归因解决方案归因。使用attribution_source参数区分回发类型。

回调宏

回传宏(名称)

描述

格式和示例 Relevant to in-app events only

benefit_score

(PredictSK) A normalized weighted average of 3 KPI scores (engagement, monetization, retention). The score is from 1 to 9 (1 being the lowest, 9 the highest, and 0 is for users with insufficient data). 

Integer

 

engagement_score

(PredictSK) A score that estimates the quantity and quality of user interaction with the app. The score is from 1 to 9 (1 being the lowest, 9 the highest, and 0 is for users with insufficient data).  

Integer

 

monetization_score

(PredictSK) A score that estimates how much revenue the user is expected to generate (including in-app purchases and ad revenue). The score is from 1 to 9 (1 being the lowest, 9 the highest, and 0 is for users with insufficient data).

Integer

 

retention_score

(PredictSK) A score that estimates how long a user is expected to continue using the app. The score is from 1 to 9 (1 being the lowest, 9 the highest, and 0 is for users with insufficient data). 

Integer

 

site_id

发布广告的应用程序(源应用程序ID)

字串:876534

 

install_time

Estimated by AppsFlyer based on the updateConversion window. Provided as a 10-digit UNIX epoch timestamp or as a human-readable timestamp

  • 字符串:1596119460
  • 转换为 2020 年 7 月 30 日 UTC 时间 14:31
 

skadnetwork_ad_network_time

Time the postback was received by the ad network from the iOS device. Reported by the ad network. Provided as a 10-digit UNIX epoch timestamp or as a human-readable timestamp

  • 字符串:1596119460
  • 转换为 2020 年 7 月 30 日世界标准时间 14:31



 


skadnetwork_received_time

Time AppsFlyer received the postback from the ad network. Provided as a 10-digit UNIX epoch timestamp or as a human-readable timestamp

 

  • 字符串:1596119460
  • 转换为 2020 年 7 月 30 日世界标准时间 14:31

 

event_name

事件名称 

  • af_skadnetwork_revenue
  • af_login
  • af_skadnetwork_revenue
  • 或由广告主设置

String: af_skadnetwork_revenue, abc123

 

收入

使用指定的货币代码的收入金额

数字:5,20,0.4

currency

货币代码是广告主设置的应用专用货币

字符串:EUR,USD,ZAR

attribution_source

归因数据的来源:

SKAdNetwork: SKAdNetwork

String: SKAdNetwork

 

app_id

App ID (广告主 app)

字串:ID123456790

 

国家

Install geo (country) determined by the ad network

字串:US,UK,ZA

 

campaign

广告系列名称使用从广告平台回调的d-network-campaign- name 填充

字符串:UA_US_23 +

 

campaign_id

使用广告平台回调中发送的广告系列 ID 填充广告系列 ID

字串:3456745

 

redownload

可能的值:true,false

当 redownload = true, 意味用户从应用商店再次下载App

Boolean 值:true / false

 

skadnetwork_ambiguous_event

Events received during the first 72-hours after an advertiser changes the SKAN settings in the dashboard. Due to the various timers employed by SKAN AppsFlyer can't map the event accurately.

Boolean 值:true / false

 

skadnetwork_campaign_id

SKAN campaign ID as provided by the original SKAN postback

56, 23

 

af_skadnetwork_nonce

唯一的随机标识符,使合作伙伴能够识别重复的回调

 

 

event_id

广告平台定义的应用内事件名称/ID。   

 

transaction_id

SKAN postback transaction ID

注意: 广告客户必须明确允许我们与您共享transaction_id。 请广告主在AppsFlyer后台的 对接 模块进行操作。

 

 

 

ad_network_adset_id Added to the iOS postback by the ad network 字符串  
ad_network_adset_name Added to the iOS postback by the ad network 字符串  
ad_network_ad_name Added to the iOS postback by the ad network 字符串  
ad_network_ad_id Added to the iOS postback by the ad network 字符串  
SKAN_min_event_counter See note (1)

Integer

SKAN_max_event_counter See note (1)

Integer

SKAN_min_time_post-install See note (2)

Integer

SKAN_max_time_post-install See note (2)

Integer

SKAN_min_event_revenue See note (3) Real number
SKAN_max_event_revenue See note (3)

Real number 

fidelity-type

Differentiate between ad presentation options that affect attribution. Indicated using the values 0 and1 as follows: 

  • View-though ads (0)
  • Storekit-rendered ads (1)
Integer  
skad_af_attribution_flag

Used to indicate if the user was attributed by AppsFlyer using the Single Source of Truth mechanism

布尔  

注释:

  1. Event occurrences: The number of event occurrences is calculated using the following formula:
    [round up (SKAN_min_event_counter+SKAN_max_event_counter) / 2]
    Note! The value must be rounded up to the nearest integer.
    • 示例:
      • A. If min=0 and max=1 the number of events is 1.
      • B. If min=0 and max =10 the number of events is 5.
  2. Determine install time: For advertisers implementing custom conversion, AppsFlyer calculates install time as the postback arrival time - 48h - average (min_time_post_install + max_time_post_install). Ad networks don't need to make use of these macros.  
  3. Determine revenue: AppsFlyer uses these values to determine the revenue of an event by calculating the average of min and max. Ad networks don't need to make use of these macros. 
回调给广告平台的宏

SKAN postback examples

Example of an install SKAN postback sent by AppsFlyer

http://YourCompanyDomain.com/event?site_id=(publisher-id)&install_time=(timestamp)
  &skan_ad_network_time=(timestamp)
  &skan_af_received_time=(timestamp)
  &attribution_source=skadnetwork
  &app_id=(id123456789)&country=(ZA)&campaign=(campaign-name)
  &campaign_id=(campaign-id)&SKAN_ambiguous_event=(boolean)
&redownload=(boolean)
&af_SKAN_nonce=(uuid)

Example of an in-app SKAN postback sent by AppsFlyer

http://YourCompanyDomain.com/event?site_id=(publisher-id)&install_time=(timestamp)
  &skan_ad_network_time=(timestamp)
  &skan_af_received_time=(timestamp)&revenue=(value)
  &currency=(code)&event_name=(event-name)&attribution_source=skadnetwork
  &app_id=(id123456789)&country=(ZA)&campaign=(campaign-name)
  &campaign_id=(campaign-id)&SKAN_ambiguous_event=(boolean)
&redownload=(boolean)
&af_SKAN_nonce=(uuid)

如何测试

若要测试与AppsFlyer的对接,可使用以下任一方法: 

  • Real SKAN postbacks: based on actual SKAN traffic received by the network
  • 模拟回调:基于AppsFlyer的测试应用

To receive real SKAN postbacks from iOS devices, the ad network completes the following:

接收模拟回调:

  • 邮件联系 integrations@appsflyer.com申请使用测试App进行SKAdNetwork模拟回调测试。
  • 在邮件中明确测试AppID。

真实环境测试

Using this method, the ad network sends AppsFlyer actual SKAN postbacks from live apps. 

操作方 行动
广告平台 Notify AppsFlyer via your partner development manager (or email to integations@appsflyer.com) as to your SKAN network ID, provided by Apple.
广告平台和AppsFlyer 确认参与测试的客户(已集成了最新的AppsFlyer SDK)。
广告平台 Send app SKAN postbacks to AppsFlyer, using one of the methods described in this article.
AppsFlyer 根据广告客户设置的转化价值映射关系,将解码后的应用内事件信息发送到广告平台。
测试对接
操作方 行动
广告平台 Notify AppsFlyer as to the quantity of SKAN postbacks sent during a specified period for the agreed mutual customer.
AppsFlyer 对比收到的回调数量与广告平台发送的数量。
AppsFlyer

通知广告平台在解码转化值后向广告平台发送的回调事件类型和数量:

  • 激活/卸载重装后激活
  • 应用内事件
Note: If you use the same endpoint for probabilistic postbacks, ensure that you filter using attribution_source=skadnetwork to distinguish SKAN Network postbacks from other postbacks.
测试成功标准:

 模拟回调

  • 使用此方法,广告渠道先将AppsFlyer预先准备的测试应用的回调内容发送到AppsFlyer(如下表),AppsFlyer再把解码后的转化信息回调给广告渠道。
  • 每个测试app都有一个不同的转换值映射,如表中所示。
App ID 转化映射模式 Instructions
id888707085

收入映射模式,且转化值每增加1,代表收入增加$1

Expected results: 

  1. In the Integration tab, enable in-app events postbacks
  2. Select event name af_SKAN_revenue and map to your event identifier.
  3. Save configuration.
  4. In a postback, send conversion value = 7.
  5. AppsFlyer responds with:
    • 1次激活
    • af_SKAN_revenue postback with value of $7
id888707086 应用内事件模式,且记录以下事件:
  • af_level_complete
  • af_login
  • af_SKAN_revenue
  • af_register
  • af_subscription
  • af_custom_event
  1. In the Integration tab, enable in-app events postbacks
  2. Select each of the in-app events listed and map it to your event identifier. 
  3. Save configuration.
  4. In a postback, send conversion value = 63.
  5. AppsFlyer responds with:
    • 1次激活
    • af_level_complete
    • af_login
    • af_SKAN_revenue postback
    • af_register
    • af_subscription
    • af_custom_event
id888707087 Engagement, measured using af_SKAN_revenue event
  1. In the Integration tab, enable in-app events postbacks
  2. Map the event name af_SKAN_revenue and to your event identifier.
  3. Save configuration.
  4. In a postback, send conversion value = 3.
  5. AppsFlyer responds with:
    • 1次激活
    • 3 postbacks of af_SKAN_revenue event
操作方 行动
广告平台 Configure your SKAN network ID (provided by Apple) and SKAN postback template on the postback management platform. For queries and assistance, contact integrations@appsflyer.com.
广告平台
  1. Activate the test apps.
  2. For each app complete the instructions column in the previous table. 
  3. Send simulated postbacks, using the test apps listed in the preceding table. Considerations when sending simulated postbacks:
    • 模拟回调里使用上表中列出的app_id和转换值。 
    • 此时由于广告网络无法生成Apple兼容的签名,因此模拟的回调不必包括签名字段。AppsFlyer不会验证模拟回调中的签名。
    • AppsFlyer支持广告平台使用POST或REDIRECT方法回调。
AppsFlyer 对模拟回调中的转化值进行解码并再次回发给广告平台
操作步骤
操作方 行动
AppsFlyer 处理广告平台发来的模拟回调并将解码后信息发送到广告平台。
广告平台
  • 广告平台接收解码后的回调。
  • In-app postbacks sent by AppsFlyer match the expected flows. For example, conversion value 3 for app ID888707087, the ad network receives 3 postbacks of af_SKAN_revenue event. 
测试成功标准:

说明

有关必填字段,功能扩展,认证等的说明。

常见问题解答

关于回调的问题及解答

这些添加的字段是强制的吗?

就目前而言,即使缺少一个或多个添加参数,我们也将对其进行处理。考虑到出于以下原因的信息:

  • 广告广告系列ID :如果我们与您对接了广告消耗,则会使用您的广告系列ID进行报告。
  • 广告广告系列名称:部分广告主关联广告系列名称而非广告系列ID。
  • IP地址:地理位置解析需要。
  • 时间戳:帮助我们将安装归因于正确的日期。

Can we send either our campaign ID, or our campaign name, but not both?

请参阅上一个答案。考虑使用相同的值填充ID和名称。

我们正在使用添加数据维度后转发的方式。是否可以添加不在AppsFlyer规范中的转化值?

可以。如果归因签名有效,我们将处理回调并忽略其他信息

Are the SKAN postback templates distinct from the existing postback templates?

是的。工作流程和结构不同。

Will we receive a SKAN postback and a probabilistic/deterministic modeling postback related to the same install, meaning duplicate reporting of the same install?

是的。对于每种情况,我们都会记录归因于您的安装,无论使用哪种方法,我们都会向您发送回调。

Use attribution_source to differentiate SKAN postbacks.

 

是否需要处理来自AppsFlyer的回调?

不。请考虑一下,最好的优化广告的方式是根据回调中的用户质量。

Are we expected to call AppsFlyer attribution links or is it sufficient to send the postback with the SKAN payload and enriched data?

It is sufficient to send us the SKAN payload and enriched data.

What is required for us to be certified in the AppsFlyer dashboard as a SKAN integrated partner?

  • 使用本文列出的方法之一完成集成
  • 使用AppsFlyer作为归因合作伙伴,向我们发送应用的回调

How does the limit of 100 SKAN campaign IDs impact me

The 1-100 limit relates to the way you sign and number your campaigns in Apple. It means that at any time, you can have 100 simultaneous unique campaigns. We allow you to enrich the postback with your actual campaign name and ID. Meaning you map the SKAN campaign ID to your actual campaign IDs in use at the time the postback is received. Doing so means that the 100 ID limit does not restrict the number of campaigns that you measure in AppsFlyer provided of course that you don't have more than 100 simultaneous campaigns for a given app. 

这篇文章有帮助吗?