我们能为您提供什么帮助?

PBA的Web服务器到服务器事件API(Web-S2S)

  • 更新

概要:使用Web服务器到服务器(Web-S2S)事件API报告未通过Web SDK报告的事件和转化到PBA。

5107_Infographic_Web_S2S_759x270_option1.jpg

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

面向基于人群的归因的Web-S2S API补充了Web SDK,允许营销人员报告发生在其网站上的事件,但超出了Web SDK的范围。例如,网站的访客(网络用户)触发了一个在线支付事件,由后端系统处理。处理后,后端使用S2S API将事件报告给AppsFlyer。

通过S2S API发送的事件:

  • 与Web SDK报告的事件记录方式相似
  • 如果设置为转化事件,则包含在PBA仪表板中
  • 用event_source field填充PBA原始数据,设置为web S2S

API使用说明

使用以下部分创建您的API调用。 

不可以。 注意事项 说明
1 唯一用户ID
  • 努力提供我们可用的最佳唯一用户ID。这对数据分析有重大影响。
  • 最佳实践是发送customerUserId。如果不可用,请发送afUserId,即由WebSdk设置的网站cookie ID。
  • 在任何时候,您将客户用户ID(CUID)与afUserId关联时,发送包含两个ID的setCuID()消息。
2 时间戳
  • AppsFlyer对传入事件时间戳应用严格验证:
    • 迟到的事件:如果事件在其所属日期的24小时内到达,则接受其原始时间戳。例如, 如果在周二 23:59:59 UTC之前的任何时间发送,带有周一时间戳的事件(2025-08-18 23:59 UTC)将保留该时间戳。如果在星期二23:59:59 UTC之后发送相同的事件,时间戳将被服务器接收时间覆盖。
    • 未来时间戳:不允许有时间戳晚于实际到达时间的事件。这样的时间戳也会被服务器接收时间覆盖。
  • 时间戳是基于UTC的。如有必要,在填充参数之前将本地时间转换为UTC时间。
3 收入和货币 即使它们包含在eventValue中,您也必须填充eventRevenueCurrency和eventRevenue。这样做是因为我们在仪表板中使用它们。

API基础信息

API实现需要在仪表板中可用的以下凭据:

  • 包ID(即品牌包ID)
  • (WEB_DEV_KEY)。

获取凭据:

  1. 从AppsFlyer后台的顶部菜单栏中选我的应用 > 查看品牌套件。
    包的列表显示。
  2. 复制并记录适当的:
    • 品牌套件 ID
    • (WEB_DEV_KEY)。

Web S2S API基础知识

路径

https://webs2s.appsflyer.com/v1/bundleId/method

  • 回传数据接收时间:应用包ID是否在仪表板中可用。 
  • 完成以下任一操作:
    • event:发送可报告的后端事件
    • setCuId: 在将afUserId与您的CUID关联时发送
HTTP方法 POST
内容类型要求 application/json 
JSON的payload限制 

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

拉取频次限制

POST限制量:每分钟60,000个POST请求。如需提高限额,请联系您的CSM。

TLS

setCuId方法

方法名称

setCuId

使用场景 

将CUID与您网站的访客关联时。例如,每当您将网络afUserId与您的客户用户ID匹配时。这样可以使PBA匹配来自各种来源的数据。这类似于setCustomerUserId在网站上的用法。

方法路径

https://webs2s.appsflyer.com/v1/bundleId/setcuid

Payload

JSON有效负载由此处列出的参数组成。所有参数都是必需的。

 Curl示例setCuId


curl --location --request POST 'https://webs2s.appsflyer.com/v1/bundleId/setcuid' \ --header 'Accept-Encoding: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerUserId": "1234567890abcdef", "afUserId":"9999999-f848-4963-a091-568f0bf9a361", "webDevKey" : "99999999-9999-9999-9999-999999999999"}

事件类型

方法名称

event_

使用场景 发送
方法路径

https://webs2s.appsflyer.com/v1/bundleId/event

 详情 事件方法详细信息本节包含有效负载详细信息、Curl示例、Python示例和测试建议。

事件方法详细信息

Payload参数

有效负载参数分为用户标识符和事件参数。 

  • _user_id您必须至少发送一个用户ID参数。
  • event_根据需要发送必需参数和可选参数。

用户标识符参数(至少发送一个参数)

用户ID参数  说明

customerUserId

客户用户ID(CUID)是由您设置的唯一标识符。

  • 使用相同的标识符通过任何方式报告的事件到 AppsFlyer。这意味着在 Web SDK、移动 SDK 和 S2S API 中使用相同的标识符。
  • Web SDK 客户用户 ID
  • 格式:字符串
  • 例如: "customerUserId" : "663274"
  • 填充原始数据字段:customer_user_id

afUserId

Web SDK 为每个访问您网站的用户分配的唯一用户 ID。您需要将 cookie 值传递给您的后端服务器。

  •  Cookie 详情:
    • 名称:afUserId
    • 值:将 afUserId  设置为此值
    • 域:网站域名
  • 示例:"afUserId" : "unique_cookie_uuid"
  • 填充原始数据字段:af_web_id

事件参数

参数名称 必须配置 说明

webDevKey

是

使用仪表板上可用的 web dev key 填充。

  • 示例:"webDevKey" : "ffffffff-ffff-ffff-ffff-ffffffffffff"
事件类型 是

AppsFlyer 内部使用的事件属性标识符。始终设置为 EVENT.

  • 例如: "eventType" : "EVENT"
eventName 是
  • 我们使用此参数通过营销人员在 PBA 设置中设置的 事件转换列表 来区分转换和非转换事件。 
  • 确保用与营销人员的转换逻辑一致的值填充它。
  • 格式:字符串
  • 例如: "eventName" : "web_purchase"
  • 填充原始数据字段:event_name
timestamp 否

事件发生的时间(以毫秒为单位)。作为 Unix 时间戳 发送,具有 13 位数字。

  • 如果未发送时间戳,则使用服务器时间设置时间。 
  • 事件延迟到达时使用当前服务器时间戳记。 延迟是指在事件发生后的午夜 UTC 之后到达。例如,发生在星期一的事件 必须 在星期二的午夜 UTC 之前处理。 
  • 具有未来时间戳的事件(相对于当前服务器时间)将以服务器时间进行时间戳。
  • 格式:Int
  • 例如: "timestamp" : 1584835200123
  • 填充原始数据字段:event_time
Event value 否
描述事件的事件参数映射。用于发送富应用内事件,如商品SKU、单价。
  • 关于收入的说明!您可以用收入详情填充此参数。此外,您必须填充 eventRevenue, 和 eventRevenueCurrency.
  • 格式:JSON
  • 举例来说, 要发送 SKU ABC123,颜色为蓝色,单价为 $3.99,请将 eventValue 设置为:
    {"Purchase": {"sku" : "ABC123", "color": "blue", "unit_price":3.99,"currency": "USD"}}
  • 局限性: 1000个字符。超出部分将被截断。
  • 填充原始数据字段: event_value
eventRevenueCurrency 否

收入事件的货币代码,为三字符 ISO 4217 货币代码。

  • 默认USD
  • 格式:字符串
  • 示例: "eventRevenueCurrency" : "EUR"
  • 填充原始数据字段:event_revenue_currency
事件收入 否 

分配给事件的收入(货币价值)。

请注意:如果收入在 eventValue, 中报告,也请在 eventRevenue 中报告,并填充 eventRevenueCurrency。 

  • 允许负值。例如,退款。
  • 格式:浮点数 
  • 示例值:1、1.2、1234.20
  • 填充原始数据字段:event_revenue
eventCategory 否  此参数已弃用,将在未来某个日期从系统中删除。请改用 eventValue。
eventLabel 否 

此参数已弃用,将在未来某个日期从系统中删除。请改用 eventValue。

_referrer 否

HTTP Referrer

  • 格式:字符串
  • 比如
  • 填充原始数据字段: http_referrer
userAgent 否 

用户代理请求 由浏览器发送到服务器。

  • 在可能的情况下发送此值,因为它有助于确定设备类型。 
  • 格式:字符串
  • 比如
  • 填充原始数据字段: user_agent
ip 否

用户 IP 地址

  • 在可能的情况下发送此字段的值。它有助于确定用户的 地理位置。
  • 格式:字符串
  • 比如
  • 填充原始数据字段: ip
 

Curl示例

curl --location --request POST 'https://webs2s.appsflyer.com/v1/bundleId/event' \
--header 'Accept-Encoding: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"customerUserId": "1234567890abcdef",
	"afUserId":"9999999-f848-4963-a091-568f0bf9a361",
    "webDevKey" : "99999999-9999-9999-9999-999999999999",
    "ip" : "192.0.2.1",
	"eventType":"EVENT",
	"timestamp" : 1234567890123,
	"eventName":"my_web_event",
	"eventRevenueCurrency" : "EUR",
	"eventRevenue" : 1234.56,
	
		"eventValue": {
		"purchase":{
		 "shoes": "color",
		 "quantity" : "3",
		 "Revenue" : "1234.56",
		 "Currency" : "ZAR"
		}
	}

}'

Python示例

''' using the requests python package, install using pip install requests  '''
import requests
url = "https://webs2s.appsflyer.com/v1/bundleId/event"
payload = {
    "customerUserId": "1234567890abcdef",
    "afUserId": "9999999-f848-4963-a091-568f0bf9a361",
    "webDevKey": "99999999-9999-9999-9999-999999999999",
    "ip": "192.0.2.1",
    "eventType": "EVENT",
    "timestamp": 1234567890123,
    "eventName": "my_web_event",
    "eventRevenenuCurrency": "EUR",
    "eventRevenue": 1234.56,
    "eventValue":
        {
            "purchase":
            {
                "shoes": "color",
                "quantity": "3",
                "Revenue": "1234.56",
                "Currency": "ZAR"
            }
        }
    }
headers = {
    'Accept-Encoding': 'application/json',
    'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text.encode('utf8'))

测试

出于测试目的,发送多个事件如下:

  1. 发送事件。
  2. 确保您获得200 OK返回代码。如果没有,请根据返回代码和错误消息采取纠正措施。
  3. 在协调世界时(UTC)午夜后等待几个小时,以查看PBA原始数据中报告的事件。您必须等待,因为PBA数据每天处理一次。 

其他相关信息

获取Web开发密钥

 如需获取网页开发者密钥:

  1. 在AppsFlyer中,转到我的应用选项卡。
  2. 点击查看品牌套件。

    GetWebDevKeyPba_us-en.pn

  3. 复制所需的Web Dev Key 

提取Web SDK afUserID

  • afUserId是一个唯一标识符,由Web SDK在用户首次访问您的网站时设置。
  • 如果您需要afUserId,请使用以下方法之一。


从HTTP cookie头中获取afUserId

  • afUserId由访问者的浏览器在调用您的网站时发送。
  •  如有需要,从HTTP cookie头中提取。


在访问者的浏览器中查看afUserId

  •  在访问者的浏览器中查看afUserId,以进行故障排除和调试。
  • 为了使其可用,访问者需要至少访问一次包含Web SDK的页面。 
  • 包含afUserId的cookie是与您的域相关的第一方cookie。
  • 以下程序是使用Chrome 81准备的。不同浏览器和操作系统之间可能存在一些差异。

要从访问者的浏览器获取afUserId:

  1. 在您的浏览器中,访问您的网站。
  2. 右键单击,选择 检查
    浏览器的检查元素窗口打开。

    S2S_inspect.jpg

  3. 转到 (A) 应用程序 选项卡。
  4. 在侧边菜单中,(B) 展开 Cookies。
  5. 选择您的网站。如果未显示,请刷新浏览器。
  6. 在 (C) 过滤器 字段中,输入 afUserId
    afUserID 的值显示。

响应代码

响应代码 响应消息 如何处理
200 OK  
404 Not found(未找到)
  • 检查端点 
  • 检查 Bundle ID 是否正确
400 Bad request(请求无效)
  • JSON 中存在错误。查看错误消息以获取详细信息。 

问题排查

  • 问题描述HTTP 返回代码未返回
    解决方案: AppsFlyer服务器加白

发布说明


Web SDK发布说明
Date  端点版本* 说明
2020-05-12 1  初始发布
21 1  
* 版本号与端点版本号相关。https://webs2s.appsflyer.com/v1/method