适用于移动设备的服务器到服务器事件API(S2S移动设备)

简介 :移动端的服务器到服务器(S2S)事件API将应用程序外部发生的事件发送到AppsFlyer。S2S事件的归因类似于SDK事件,并且可适用于整个平台。

S2S_us-zh.png

适用于移动设备的服务器到服务器事件API

AppsFlyer平台对由AppsFlyer SDK和API发送的移动应用程序事件进行归因和记录。使用S2S API报告应用程序外部发生的事件;例如,用户使用您的Web界面续订订阅。一旦记录了S2S事件,就可以在整个平台上使用它,包括控制面板,原始数据和分析报告。有关PBA Web事件,请参阅Web S2S for PBA。

AppsFlyer将以下信息填充到S2S事件:

  • S2S消息中发送的值
  • 某些AppsFlyer激活归因的值,例如激活时间和媒体渠道。

API使用说明

使用以下各节中包含的信息创建您的API调用。

S2S API事实

API节点(endpoint)

https://api2.appsflyer.com/inappevent/app_id

  • app_id :在AppsFlyer面板中使用的应用程序标识符。完全按照面板上显示的方式填入。
  • iOS应用程序:确保以id为前缀否则,将返回有效的200 OK返回码;但是不记录事件。
  • Windows:从Microsoft App Store获取应用ID。
  • Android示例: https://api2.appsflyer.com/inappevent/com.appsflyer.myapp
    iOS: https://api2.appsflyer.com/inappevent/id123456789
    Windows: https://api2.appsflyer.com/inappevent/a1b2c3d4e5f6
HTTP方法 POST
接受的内容类型 application/ json
授权

--header'authentication: dev_key'

  • 开发者秘钥 dev_key 是header里面的authentication token. 
  • 要获取开发者密钥(dev key),请在AppsFlyer中转到,   应用程序设置 > 开发者秘钥(dev key)
服务器获取响应消息允许列表

如果您的服务器位于防火墙外面,则将AWS IP地址范围加入白名单以获取响应消息。

JSON有效负载限制

JSON有效负载大小:最大1KB

拉取频次限制

POST限制数量:每分钟60,000 POST。要增加此限制,请联系您的CSM。

编码说明
编码URLs

将所有的保留字符进行URL编码(百分比编码)处理 (https://tools.ietf.org/html/rfc3986#section-2.1 )在最终生成URL之前。

TLS

使用TLS 1.2或更高版本。支持的密码

S2S API事实

有效负载参数

  • Payload parameters consist of one or more device identifiers (depending on the operating system).
  • What if I can't send a device identifier?
    • You may be unable to send the identifier for a reason out of your control, for example, because the user has limited ad tracking (LAT) or uses iOS 14, and did not give ATT consent (no IDFA).
    • If this is the case, be aware that not  sending an advertising ID/device identifier can cause attribution failure,  meaning that AppsFlyer can't attribute the event to the media source Events are recorded and do display in reports and dashboards. 
操作系统 标识符名称 描述

iOS

iconAFios.png

 

idfa 

如可获取,此处填充设备IDFA

格式:字符串

例如: "idfa": " 9876F1SS-2983-3855-27RR-2R626772VFNB "

idfv

如可获取,此处填充设备IDFA

格式: String
示例: "idfv": "95C9BD22-4A4C-41C8-9548-ED07C5C8C145"

Android

iconAFand.png

advertising_id

在可用的地方填充设备GAID(广告ID)

格式:字符串

示例: "advertising_id": " 9c9a82fb-d5de-4cd1-90c3-527441c11828 "

oaid

格式:字符串

例如: "oaid": " 1fe9a970-efbb-29e0-0bdd-f5dbbf751ab5 "

amazon_aid

格式:字符串

imei

格式:字符串

例如: "imei": " AA-BBBBBB-CCCCCC-D "

设备标识符
参数名称 强制性的内容 描述

appsflyer_id

应用程序首次启动时由AppsFlyer生成的唯一标识符。

  • 格式:字符串
  • 示例: "appsflyer_id": "1415211453000-6513894"

CUSTOMER_USER_ID

客户用户ID(CUID),  应用所有者设置的唯一用户标识符。

  • 格式:字符串。
  • 示例: "customer_user_id": "my_customer_number1234"

att

iOS ATTrackingManager授权状态

  • 如果设备操作系统版本为iOS 14或更高版本,请使用ATTrackingManager填充att
    • 格式:一位数,整数
    • 示例: 1
  • The iOS values forATTrackingManager are:
    • 0: Not determined
    • 1: Restricted
    • 2: Denied
    • 3: Authorize

注意!

  • As part of Apple privacy policies, we recommend that you populate att with the ATTrackingManager value. 
  • 您可以在iOS14正式版之前发送此参数。我们会在正式发布后,对其进行处理。

 

ip

事件发生期间的移动设备的IP地址。

  • 如果发送,则使用IP地址填充地理位置字段。
  • 如果未发送,AppsFlyer将使用激活归因事件中的值填充IP地址和地理位置字段。
  • 格式:包含IPV4或IPV6地址的字符串
  • 示例: "ip": "192.0.2.1
af_events_api 弃用
  • 从2020年7月6日开始弃用。
  • 不需要此参数,您可以停止发送它。这样做不会以任何方式影响归因。

eventName

指定事件名称。确保事件名称与营销商的要求一致。

  • 格式:字符串
  • 示例: "eventName": "af_purchase"

Event value

If you send an event without a value then send: "eventValue":""

  • 事件值必须不含其他额外的符号或添加格式。
  • 对于af_revenue可以使用十进制逗号。负值前应加上-
  • 格式:JSON中的字符串
  • 示例: "eventValue": " { \"af_revenue\": \"6\", \"af_content_type\": \"wallets\", \"af_content_id\": \"15854\", \"af_quantity\" :\"1\" } "

app_version_name

您的应用版本或标识符。

  • 格式:字符串
  • 示例: "app_version_name": "my_app_version"

app_store

Equivalent to AF_STORE in Android apps. The store from which the app was downloaded. 

  • Raw data field: Install App Store
  • 格式:字符串
  • Example: my_android_store_is_best

事件时间

事件发生的时间使用UTC时区。

  • 默认值:如果未发送eventTime ,则将时间设置为HTTP消息到达时间。
  • 格式:字符串yyyy-mm-dd hh:mm:ss.sss时间需要使用UTC时区。
  • 示例: "eventTime":"2019-05-15 12:17:01.123"表示世界标准时间(UTC+0)12:17:01。

一天结束:

  • 如果您要使eventTime生效,该事件必须在第二天的02:00前到达AppsFlyer。这意味着,如果事件发生在世界标准时间(UTC+0)星期一17:00,则必须在世界标准时间(UTC+0)星期二02:00之前到达AppsFlyer服务器。
  • 一天结束后收到的事件均按照实际到达时间标记。
  • 具有未来时间(即到达时间之后)的事件会标记成到达时间。

示例

  • 时间使用世界标准时间(UTC时间)
  • 发送事件的时间为 eventTime = Monday 21:00。
到达时间 AppsFlyer记录的时间 备注
星期二01:00 星期一21:00 营业结束前到达。
星期三09:00 星期三09:00 营业结束后到达。时间设置为到达时间。

eventCurrency

货币代码使用ISO 4217 3-字符代码和BCN(比特币)

  • 默认值:美金
  • 示例: "eventCurrency": "ZAR"

bundleIdentifier

唯一的应用程序标识符。在原始数据中,该参数填充Bundle ID。

  • 格式:字符串
  • 示例: "bundleIdentifer": "com.myapp"

sharing_filter

sharing filter将阻止与合作伙伴和其他第三方通过回调/ API共享S2S事件。

使用过滤器可满足GDPR和CCPA等法规要求,遵守用户选择退出机制以及其他业务逻辑。

Sharing_filter具有以下选项:

  • 全部:所有合作伙伴均被阻止。不要与任何人分享事件。示例: "sharing_filter": "all"
  • 合作伙伴ID的系列列表。格式[“ partnerid_1”,“ partnerid_2”,“ partnerid_n”]示例: “ sharing_filter”:[“ googleadwords_int”,“ adcolony_int”]

合作伙伴ID的列表,请联系您的CSM或AppsFlyer技术支持。

Curl example

curl --location --request POST 'https://api2.appsflyer.com/inappevent/<app_id_placeholder>'\
--header 'authentication: <dev_key_placeholder>
' \
--header 'Content-Type: application/json' \
--data-raw '{
  "appsflyer_id": "9999999999999-9999999999999999999",
	"advertising_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
	"customer_user_id" : "example_customer_id_123",
	"ip": "199.0.2.1",
	"app_version_name" : "example_version_name",
	"eventTime" : "2020-02-25 12:00.000",
	"eventName": "af_purchase",
	"eventCurrency": "ZAR",
	"eventValue": 
	"{
		\"af_revenue\": \"1006\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }"
}
'

响应代码

响应代码 信息 如何处理
200 OK

收到消息后,将执行最小数据验证。这样,即使事件可能未完全记录在AppsFlyer中,您也可以获得OK响应。调试(debug)事件:

  • 使用本文中的CURL example”
    • 更新应用程序ID(app id)和开发者密钥(dev key)的详细信息。
    • 更改appsflyer_id和eventTime参数。使用当前时间和最近归因于非自然的appsflyer_id。
  • 发送呼叫。
    • 它应返回200 OK的消息。
    • 检查事件是否记录正确,包括收入
    • 根据需要进行其他更改,然后再次测试。
400 无法进行身份验证 确保身份验证密钥(authentication key)正确。
400 appsflyer_id 是必填字段
  • 确保在 JSON中含有正确的AppsFlyer ID。
  • JSON是stringified()且格式正确。
401 未经授权 authentication header中提供的密钥不是此应用程序的开发者秘钥<dev_key>。
400 错误的请求

至少要有一项验证标准请求失败。

400 有效载荷丢失或解析失败
  • 确保 JSON 已经字符串化且格式正确。
  • JSON有效内容中是否包含多个事件。确保每次请求只发送一个事件。
500 内部服务器错误 验证JSON是否为stringified()且格式正确。
 

测试

考虑:

  • 对于测试,请使用非自然激活的AppsFlyer ID,以便测试事件能实时进行归因。自然事件的归因会延迟几个小时。
  • 事件的某些字段是根据用户的激活归因事件填充的。例如,激活时间和媒体渠道。

要将测试设备归为非自然激活:

  1. 准备自定义归因链接,用于 S2S 消息测试。将链接上的媒体渠道参数设置为s 2s_test 。示例: &pid=s2s_test
  2. 注册测试设备
  3. 从测试设备上卸载应用程序。
  4. 将链接发送到测试设备。
  5. 点击链接
  6. 安装并启动该应用程序。
  7. 在面板上,检查激活是否被归因了。
  8. 提取AppsFlyer ID 以在您的S2S消息中使用。

发送S2S测试消息

  1. 使用分配的AppsFlyer ID准备S2S消息。有关代码示例,请参见以下内容。
  2. 发送消息。
  3. 请执行以下一项操作,以查看AppsFlyer如何记录该消息:
  4. 检查并查看:
    • S2S消息中发送的值正确填充了报告。请特别注意“事件日期”,“事件币种”,“事件收入”和“事件值”字段。
    • 归因渠道和激活时间由AppsFlyer填充。
    • SDK本身提供的值(例如SDK版本)不会被填充。

发送S2S消息的示例代码

JavaPythonNode JSC#PHPGo
/* using the okhttp package 
install from maven https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp */
import okhttp3.*;
import java.io.IOException;

public class SendRequest {
  public static void main(String[] args) {

    OkHttpClient client = new OkHttpClient();
    MediaType mediaType = MediaType.parse("application/json");

    RequestBody body = RequestBody.create(mediaType, "" +
        "{\r\n\t\"appsflyer_id\": \"<APPS_FLYER_ID>\"," +
        "\r\n\t\"customer_user_id\": \"123456\",\r\n\t\"eventName\": \"af_purchase\",\r\n\t\"" +
        "eventValue\": \"{\\\"af_revenue\\\":\\\"6\\\" ,\\\"af_content_id\\\":\\\"15854\\\"}\",\r\n\t\"" +
        "eventCurrency\": \"USD\",\r\n\t\"" +
        "eventTime\": \"2018-08-10 4:17:00.000\",\r\n\t\"");

    Request request = new Request.Builder()
        .url("https://api2.appsflyer.com/inappevent/<APP_ID>")
        .post(body)
        .addHeader("Content-Type", "application/json")
        .addHeader("authentication", "<YOUR_DEV_KEY>")
        .build();

    try {
      Response response = client.newCall(request).execute();
      System.out.println(response.code());
      System.out.println(response.body().string());
    } catch (IOException e) {
      e.printStackTrace();
    }
  }
}

发送advertising ID /设备标识符很重要

  • Advertising ID /设备标识符是必填项,以确保可以发送回调数据到Facebook和Google Ads等SRN。如果您无法发送该ID,请考虑我们将无法发送回调数据。
  • 如果仅发送AppsFlyer ID,则应用内事件将被记录并正确归因。

填充参数

自然量与非自然量的区别

当AppsFlyer处理S2S应用内事件时,将使用AppsFlyer ID来识别关联应用内事件之前的激活事件来填充归因字段。

这意味着 AppsFlyer 将某些数据与非自然 S2S 应用内事件相关联, 但与自然S2S 应用内事件无关。

 示例

例如, 如果比较非自然和自然 S2S 应用内事件的原始数据报告, 则非自然事件会包含自然应用内事件所不包含的数据。

非自然应用内事件包括的数据有媒体渠道、广告系列、归因接触类型、归因接触时间等。

另一方面, 自然应用内事件来自于自然激活。自然激活没有相关的广告系列,媒体渠道,归因接触类型和激活时间等相关的数据。

将AppsFlyer ID与客户用户ID(CUID)映射

需要后端逻辑来获取值以填充参数。下面介绍如何获取AppsFlyer ID:

  • AppsFlyer ID是必要的,用于归因事件。
  • 它是在用户首次激活移动应用程序时生成的。
  • 所以您可以将CUID映射到AppsFlyer ID,您需要在应用程序中设置CUID。

为了使您更容易了解哪个用户执行了哪个事件,请执行以下流程:

  • 当用户激活应用的时候设置客户用户 ID(CUID)
  • AppsFlyer原始数据报告包含CUID和AppsFlyer ID。使用数据传递工具之一来获取或使用AppsFlyer Push API。
  • 使用原始数据报告将CUID与AppsFlyer ID匹配。
  • AppsFlyer ID在集成到您的应用程序( Android / iOS )中的SDK中可用。
  • 将AppsFlyer ID映射到内部系统中的客户用户ID(CUID)(对于将来使用很重要)。

将AppsFlyer ID与CUID映射后,即可将用户与执行的事件进行匹配。然后,您可以获取其他值(事件值,事件币种,事件时间等),并发送服务器到服务器应用内事件。  

请求正文示例

{
  "appsflyer_id": "1415211453000-6513894",
	"advertising_id": "38412345-8cf0-aa78-b23e-10b96e40000d",
	"eventName": "af_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	"ip": "1.2.3.4",
	"eventTime": "2014-05-15 12:17:00.000"
}


本示例中,AppsFlyer 收到一个 S2S 应用内事件。它表示含收入的购买事件,并包含内容类型等其他属性。

提取AppsFlyer ID

appsflyer_id是服务器到服务器事件消息中的必需参数。AppsFlyer使用此参数将事件归因于原始设备和归因的媒体渠道。您可以使用以下方法之一获取ID:

 提示

测试 S2S消息时,如果使用的是原始数据,请查找带有媒体渠道“ s2s_test”的记录。这是您的测试设备,其 AppsFlyer 设备 ID 是您所需的 ID。

发送负收入

可以发送收入值为负的事件。例如,如果购买被取消。参数af_revenue可以用负值来记录此信息。

如果您填充af_quantity ,则可能根据你们的系统逻辑使用负值填充它。AppsFlyer不使用af_quantity

负收入示例

{ 
 “ eventName”:“ cancel_purchase”, 
 “ eventValue”: 
 “ {
		\"af_revenue\": \"-6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   } ”, 
 “ eventCurrency”:“ USD”, 
 
 }

发送没有事件值的事件

If you want to send events without event value, simply pass an empty string to event value: "eventValue":""

AppsFlyer 将根据广告主的配置,向媒体渠道发送此类详细应用内事件,实现高级定向、优化和受众创建。

疑难解答

事件未显示在面板上

  • 节点(endpoint):验证使用的节点(endpoint)是正确的。
  • 验证有效负载是否包含必需参数。参阅此处
  • 确保您用来触发事件的AppsFlyer ID是真实的appsflyer_id,并且已实际储存在特定的应用程序上。不是文档中提供的测试ID。参阅此处
  • S2S事件在一个S2S请求中不支持多事件。每个事件都必须作为单独的事件发送。
  • 在数据概览面板中,日期范围与应用激活日期(LTV)相关,而与事件日期无关。
    • 确保您选择正确的日期范围。
    • 确保面板日期范围对应于设备的激活日期(appsflyer_id),而不是事件的日期。
  • 事件原始数据报告:日期范围与事件日期有关,与激活日期无关。

事件不包含收入

如果发送S2S事件,但未记录其收入:请确保对发送的JSON进行了字符串化。最重要的部分是JSON中的事件值参数。它必须按照下面的示例所示进行字符串化。

"{\"af_revenue\":\"6\" ,\"af_content_type\":\"wallets\"}"

如果未进行字符串化,则将无法正确处理事件值,也不会记录收入。

收入值不得以任何方式设置格式。它们可以包含十进制逗号,但这不是强制性的。不包括货币符号或代码也不包括,分隔符。收入可以以-为前缀

  • 有效值示例为: 123-123.45123.456 
  • 非法值示例: 1,234.561,234

S2S事件中并非所有字段都要填充

原始数据的字段即使用S2S调用中发送的值进行填充,也使用激活事件的某些字段进行填充。对于使用AppsFlyer SDK上报的应用内事件,可以观察到类似的但并不完全相同的行为。还有一些特定的不同之处,S2S事件不会填充以下字段:

  • WIFI
  • operator
  • language
  • 设备型号
  • 设备类别
  • App Version: You can use app_version_name
  • 应用名称
这篇文章有帮助吗?