Webhook 事件类型和字段

Adapty 会在订阅事件发生时发送 Webhook。本节定义了这些事件类型及每个 Webhook 所包含的数据。

Webhook 事件类型

您可以将所有事件类型发送到 Webhook,也可以只选择其中部分类型。您可以参考我们的事件流程,了解预期接收的数据格式以及如何围绕它构建业务逻辑。在设置 Webhook 集成时,您可以禁用不需要的事件类型,也可以在那里用自定义 ID 替换 Adapty 默认的事件 ID。

事件名称描述
subscription_started当用户激活不含试用期的付费订阅时触发,即立即扣费。
subscription_active在 subscription_started 事件触发后,确认订阅仍处于有效状态。您需要设置从订阅开始到此次检查之间的天数。若订阅仍然有效(包括用户已进入宽限期的情况),则会收到该事件。若订阅已到期或用户已关闭自动续订,则不会收到任何事件,Adapty 也不会再次检查。此事件仅跟随非试用订阅。试用期转化后会发送 trial_converted,该事件不会启动此检查。
subscription_renewed订阅续订且用户被扣费时触发。无论是试用订阅还是非试用订阅,此事件从第二次计费周期开始触发。
subscription_renewal_cancelled用户已关闭订阅自动续订。用户在当前付费周期结束前仍可访问高级功能。
subscription_renewal_reactivated当用户重新开启订阅自动续订时触发。
subscription_expired订阅取消后完全到期时触发。例如,用户在 12 月 12 日取消订阅,但订阅在 12 月 31 日到期,则该事件在 12 月 31 日记录。
subscription_paused当用户启用订阅暂停时触发(仅限 Android)。
subscription_deferred当您免费延长用户订阅时触发:通过 Google Play Developer API 进行延期,或通过 App Store Server API 进行续订日期延期。用户在延长后的续订日期前仍可访问高级功能。
non_subscription_purchase任何非订阅类购买,例如永久授权或消耗型商品(如游戏内虚拟货币)。
trial_started当用户激活试用订阅时触发。
trial_active在 trial_started 事件触发后,确认试用仍处于有效状态。您需要设置从试用开始到此次检查之间的天数。若试用仍在进行中,则会收到该事件。若试用已结束、已转化,或用户已关闭自动续订,则不会收到任何事件,Adapty 也不会再次检查。
trial_converted试用结束且用户被首次扣费时触发。例如,用户的试用期到 1 月 14 日,但在 1 月 7 日被扣费,则该事件在 1 月 7 日记录。
trial_renewal_cancelled用户在试用期间关闭了订阅自动续订。用户在试用结束前仍可访问高级功能,但不会被扣费,也不会开始订阅。
trial_renewal_reactivated当用户在试用期间重新开启订阅自动续订时触发。
trial_expired试用期结束且未转化为订阅时触发。
entered_grace_period付款尝试失败,且用户进入宽限期(如已启用)时触发。用户在此期间仍可访问高级功能。
billing_issue_detected扣费尝试期间发生账单问题时触发(例如,银行卡余额不足)。
subscription_refunded订阅被退款时触发(例如,由 Apple 客服处理的退款)。
non_subscription_purchase_refunded非订阅购买被退款时触发。
access_level_updated用户的访问等级更新时触发。
Note

subscription_renewal_reactivated 携带的是之前的产品 ID——即用户取消订阅时处于活跃状态的产品 ID——即使用户后来通过购买其他产品重新激活了订阅也是如此。Apple 在整个取消 → 重新激活链路中保持相同的 original_transaction_id,因此该事件反映的是原始产品。新产品将在下一个 subscription_renewed 事件中体现,届时新产品的计费正式开始。

Note

在 Google Play 上,Adapty 可能会发送 subscription_started 事件,且所有金额字段均为零——例如,当 Google 用一个订阅替换另一个订阅,或订阅以免费阶段开始时。请勿将此类事件计入收入。当 Google 替换订阅时,会生成新的购买令牌,因此 Adapty 会以不同的 store_transaction_id 上报付费交易。

Webhook 事件结构

Adapty 只会发送你在 Integrations -> Webhooks 页面 Events names 部分所选择的事件。

Webhook 事件以 JSON 格式序列化。发送到您服务器的 POST 请求体将包含序列化事件,并封装在以下结构中。所有事件遵循相同的结构,但其字段会根据事件类型、商店以及您的具体配置有所不同。用户属性是您设置的自定义用户属性,因此其内容取决于您的配置。归因数据字段在所有事件类型中保持一致,但归因列表取决于您的移动应用中使用了哪些归因来源。以下是一个事件示例:

{
  "profile_id": "00000000-0000-0000-0000-000000000000",
  "customer_user_id": "UserIdInYourSystem",
  "idfv": "00000000-0000-0000-0000-000000000000",
  "idfa": "00000000-0000-0000-0000-000000000000",
  "advertising_id": "00000000-0000-0000-0000-000000000000",
  "profile_install_datetime": "2000-01-31T00:00:00.000000+0000",
  "user_agent": "ExampleUserAgent/1.0 (Device; OS Version) Browser/Engine",
  "email": "john.doe@company.com",
  "event_type": "subscription_started",
  "event_datetime": "2000-01-31T00:00:00.000000+0000",
  "event_properties": {
    "store": "play_store",
    "currency": "USD",
    "price_usd": 4.99,
    "profile_id": "00000000-0000-0000-0000-000000000000",
    "cohort_name": "All Users",
    "environment": "Production",
    "price_local": 4.99,
    "original_price_usd": 4.99,
    "original_price_local": 4.99,
    "discount_amount_usd": 0,
    "discount_amount_local": 0,
    "base_plan_id": "b1",
    "developer_id": "onboarding_placement",
    "ab_test_id": "00000000-0000-0000-0000-000000000000",
    "ab_test_name": "onboarding_ab_test",
    "ab_test_revision": 1,
    "ab_test_variant_id": "00000000-0000-0000-0000-000000000000",
    "ab_test_variant_name": "Variant B",
    "paywall_name": "UsedPaywall",
    "proceeds_usd": 4.2315,
    "variation_id": "00000000-0000-0000-0000-000000000000",
    "purchase_date": "2024-11-15T10:45:36.181000+0000",
    "store_country": "AR",
    "event_datetime": "2000-01-31T00:00:00.000000+0000",
    "proceeds_local": 4.2415,
    "tax_amount_usd": 0,
    "transaction_id": "0000000000000000",
    "net_revenue_usd": 4.2415,
    "profile_country": "AR",
    "paywall_revision": "1",
    "profile_event_id": "00000000-0000-0000-0000-000000000000",
    "tax_amount_local": 0,
    "net_revenue_local": 4.2415,
    "vendor_product_id": "onemonth_no_trial",
    "profile_ip_address": "10.10.1.1",
    "consecutive_payments": 1,
    "rate_after_first_year": false,
    "original_purchase_date": "2000-01-31T00:00:00.000000+0000",
    "original_transaction_id": "0000000000000000",
    "subscription_expires_at": "2000-01-31T00:00:00.000000+0000",
    "profile_has_access_level": true,
    "profile_total_revenue_usd": 4.99,
    "promotional_offer_id": null,
    "store_offer_category": null,
    "store_offer_discount_type": null
  },
  "event_api_version": 1,
  "profiles_sharing_access_level": [{"profile_id": "00000000-0000-0000-0000-000000000000", "customer_user_id": "UserIdInYourSystem"}],
   "attributions": {
    "appsflyer": {
      "ad_set": "Keywords 1.12",
      "status": "non_organic",
      "channel": "Google Ads",
      "ad_group": null,
      "campaign": "Social media influencers - Rest of the world",
      "creative": null,
      "created_at": "2000-01-31T00:00:00.000000+0000"
    }
  },
  "user_attributes": {"Favourite_color": "Violet", "Pet_name": "Fluffy"},
  "integration_ids": {"firebase_app_instance_id": "val1", "branch_id": "val2", "one_signal_player_id": "val3"},
  "play_store_purchase_token": {
    "product_id": "product_123",
    "purchase_token": "token_abc_123",
    "is_subscription": true
  }
}

事件字段

各类事件的事件参数均相同。

字段类型描述
advertising_idUUID广告 ID(仅限 Android)。
attributionsJSON归因数据。在 Webhook 设置中启用 Send Attribution 后包含此字段。
customer_user_idString您应用中的用户 ID(UUID、邮箱或其他 ID),需在应用代码中识别用户时设置。若未在应用代码中识别用户,或该用户为匿名用户(未登录),则此字段为 null。
emailString用户邮箱,需通过 Adapty SDK 中的 updateProfile 方法,或通过服务端 API 创建/更新用户画像时设置。若未向 SDK 或 API 方法传入 email 值,则此字段为 null。
event_api_versionIntegerAdapty API 版本(当前版本:1)。
event_datetimeISO 8601事件的业务发生时间,例如购买事件对应购买日期,到期事件对应到期日期,而非 Adapty 接收或发送事件的时间。采用 ISO 8601 格式(例如 2020-07-10T15:00:00.000000+0000)。有关排序的说明请参见下方注意事项。
event_propertiesJSON事件属性。
event_typeStringAdapty 格式的事件名称。完整列表请参见 Webhook 事件类型。
idfaUUID广告标识符(仅限 Apple)。对应 Adapty 看板用户画像中的 IDFA。若因追踪限制、儿童模式或隐私设置而不可用,则可能为 null。
idfvUUID供应商标识符(IDFV),每位开发者唯一。对应 Adapty 看板用户画像中的 IDFV。
integration_idsJSON用户集成 ID,需通过 Adapty SDK 中的 setIntegrationIdentifier 方法,或通过服务端 API 创建/更新用户画像时设置。不可用或集成已禁用时为 null。
play_store_purchase_tokenJSONPlay Store 购买令牌,在 Webhook 设置中启用 Send Play Store purchase token 后包含此字段。
profile_idUUIDAdapty 为每个用户画像自动生成的用户画像 ID。若未识别用户或允许购买发生在登录之前,同一 Apple/Google ID 可能关联多个不同的用户画像 ID。详情请参阅 Adapty 如何处理父/继承用户画像。
profile_install_datetimeISO 8601安装时间戳,采用 ISO 8601 格式(例如 2020-07-10T15:00:00.000000+0000)。
profiles_sharing_access_levelJSON与当前用户画像共享访问等级的其他用户列表(不含当前用户)。若您的应用启用了访问等级共享,此列表将包含使用同一 Apple/Google ID 的其他用户画像。
格式:
  • profile_id:(UUID)Adapty ID
  • customer_user_id:(String)Customer User ID(如有)
user_agentString设备浏览器的 User-Agent。
user_attributesJSON可设置的自定义数据,用于为用户画像补充应用专属信息。通常用于记录用户偏好(如主题、语言)或行为标记(是否完成用户引导、功能使用情况等)。
格式为键值对,键为字符串,值可为字符串或数字(例如 {"Favourite_color": "Violet", "Pet_name": "Fluffy"})。
您可以在 Adapty 看板中针对单个用户画像手动设置自定义属性,也可通过 Adapty SDK 中的 updateProfile 方法以编程方式设置,或在通过服务端 API 创建/更新用户画像时设置。
在 Webhook 设置中启用 Send User Attributes 后包含此字段。

虽然移动应用代码中的自定义属性值可设为浮点数或字符串,但通过服务端 API 或历史数据导入的属性可能以不同格式传入,此时布尔值和整数值将转换为浮点数。

Note

event_datetime 反映的是订阅生命周期中事件发生的时间,而非 Adapty 处理或推送该事件的时间。因此,多个事件可能共享相同的 event_datetime,或以非时间顺序到达。例如,subscription_expired 事件的 event_datetime 可能早于 Adapty 先行推送的 subscription_renewal_cancelled 事件。请勿依赖 event_datetime 对事件排序。应改用自行记录的接收时间排序,并通过 profile_event_id 或交易 ID 进行去重。

归因

若要发送归因数据,请在 Integrations -> Webhooks 页面中启用 Send Attribution 选项。启用后,若你已配置归因集成,以下数据将随每个来源的事件一并发送。所有事件类型均会收到相同的归因数据。

{
  "attributions": {
    "appsflyer": {
      "ad_set": "sample_ad_set_123",
      "status": "non_organic",
      "channel": "sample_channel",
      "ad_group": "sample_ad_group_456",
      "campaign": "sample_ios_campaign",
      "creative": "sample_creative_789",
      "created_at": "2000-01-31T00:00:00.000000+0000",
      "network_user_id": "0000000000000-0000000"
    }
  }
}
字段名字段类型描述
ad_setString归因广告组。
statusString可为 organic、non_organic, 或 unknown。
channelString营销渠道名称。
ad_groupString归因广告集。
campaignString营销活动名称。
creativeString归因创意关键词。
created_atISO 8601 date归因记录的创建日期和时间。
network_user_idString归因来源为用户分配的 ID。

集成 ID

以下集成 ID 目前用于事件中:

  • adjust_device_id
  • airbridge_device_id
  • amplitude_device_id
  • amplitude_user_id
  • appmetrica_device_id
  • appmetrica_profile_id
  • appsflyer_id
  • branch_id
  • facebook_anonymous_id
  • firebase_app_instance_id
  • mixpanel_user_id
  • pushwoosh_hwid
  • one_signal_player_id
  • one_signal_subscription_id
  • tenjin_analytics_installation_id
  • posthog_distinct_user_id
  • singular_sdid

Play Store 购买令牌

此字段包含重新验证购买所需的全部数据(如有需要)。只有在 Webhook 集成设置中启用了 Send Play Store purchase token 选项后,才会发送该字段。

字段类型描述
product_idString在 Play Store 中购买的产品唯一标识符(SKU)。
purchase_tokenStringGoogle Play 生成的令牌,用于唯一标识本次购买交易。
is_subscriptionBoolean表示所购产品是否为订阅(true)或一次性购买(false)。

事件属性

事件属性因事件类型而异,即使是同类事件也可能有所不同。例如,来自 App Store 的事件不会包含 base_plan_id 等 Android 专属属性。

访问等级更新事件具有独特的属性,因此我们为其单独开辟了一个章节。同样,附加税务和收入事件属性也被单独列出,因为它们仅适用于特定的事件类型。

适用于大多数事件类型

大多数事件类型的事件属性是一致的(Access Level Updated 事件除外,该事件在其专属章节中单独说明)。下表列出了所有属性,并标注了各属性所属的具体事件。

Note

Adapty 使用 currencylayer.com 的汇率将其他货币换算为美元(每 8 小时更新一次)。汇率以交易发生时为准——此后的汇率变动不影响本次换算结果。

字段类型描述
ab_test_idUUID交易来源的 Adapty A/B 测试 ID。对于跨版位 A/B 测试,此为跨版位测试的 ID,在每个版位上均相同。详见 流程与 A/B 测试字段。
ab_test_nameString交易来源的 Adapty A/B 测试名称。对于跨版位 A/B 测试,这是某个版位上该测试的名称,格式为 <test name> child-N,其中 N 为版位编号,而非实验变体编号。若需跨版位汇总跨版位测试数据,请使用 ab_test_id,并从 ab_test_parent_name 获取其名称。
ab_test_parent_nameString交易来源的跨版位 A/B 测试名称。仅在跨版位 A/B 测试中存在。
ab_test_revisionInteger交易来源的 A/B 测试版本号。
ab_test_variant_idUUID交易来源的 A/B 测试实验变体 ID。在常规付费墙 A/B 测试中,与 variation_id 一致;在流程 A/B 测试中,与 flow_variation_id 一致;在跨版位 A/B 测试中,同一实验变体在每个版位上的值相同。可用于按测试实验变体拆分交易数据。
ab_test_variant_nameStringA/B 测试实验变体名称。对于跨版位 A/B 测试,为测试设置中的实验变体名称;对于其他测试,为实验变体名称,或在实验变体无名称时显示付费墙或流程名称。与 ab_test_variant_id 同时存在。
base_plan_idStringGoogle Play Store 中的基础方案 ID 或 Stripe 中的价格 ID。
cancellation_reasonString

可能的取消原因:voluntarily_cancelled、billing_error、price_increase、product_was_not_available、refund、cancelled_by_developer、new_subscription_replace、upgraded、unknown、adapty_revoked。

出现在以下事件类型中:

subscription_cancelled、subscription_refunded 和 trial_cancelled。
cohort_nameString决定向用户展示哪个付费墙的目标受众名称。
consecutive_paymentsInteger用户连续订阅(不中断)的周期数,包含当前周期。
currencyString本地货币。除非启用了 Send trial price,否则在 trial_started 中为 null。详见附加税务与收入事件属性。
developer_idString交易来源的版位 ID。
discount_amount_localFloat交易折扣金额:标准价格减去实际收取金额(Apple/Google 分成前),以本地货币计。全价购买时为 0。免费试用时等于完整标准价格(original_price_local),因为未实际收费。当有优惠但标准价格未知时为 null(参见 original_price_local)。对于 App Store 预付优惠始终为 null:单次预付费用涵盖多个计费周期,无法与每周期标准价格进行比较。
discount_amount_usdFloatdiscount_amount_local 对应的美元金额。
environmentString可能的值为 Sandbox 或 Production。
event_datetimeISO 8601 date事件的日期和时间,与事件根级别的值相同。
flow_idUUID交易来源的流程 ID。无论是否在 A/B 测试中,所有在流程内完成的交易均存在此字段。
flow_nameString交易来源的流程名称。与 flow_id 同时存在。
flow_variation_idUUID此版位上流程实验变体的 ID,与 SDK 返回给应用的 flow.variationId 值相同。与 flow_id 同时存在。
original_price_localFloat产品未折扣的标准价格(Apple/Google 分成前),以本地货币计。对于订阅,这是续订价格。全价购买时等于 price_local,对于一次性购买始终等于 price_local,因为商店不单独报告其标准价格。当折扣购买时商店未提供可靠标准价格时为 null(例如,自动续订已关闭、续订仍附带优惠,或正在等待产品变更)。
original_price_usdFloatoriginal_price_local 对应的美元金额。
original_purchase_dateISO 8601 date对于循环订阅,原始购买是链中的第一笔交易,其 ID(称为原始交易 ID)关联着续订链;后续交易是其延续。原始购买日期即为该第一笔交易的日期和时间。
original_transaction_idString

对于循环订阅,这是关联续订链的原始交易 ID。原始交易是链中的第一笔;后续交易是其延续。

如无延续交易,original_transaction_id 与 store_transaction_id 相同。

paywall_nameString交易来源的付费墙名称。对于流程,这是流程内付费墙屏幕的 ID(scr_...),而非名称。流程名称在 flow_name 中。
paywall_revisionString交易来源的付费墙版本号,默认值为 1。
price_localFloat交易收取的金额(Apple/Google 分成前),以本地货币计。在 trial_started 中为 null(不收费),除非启用了 Send trial price。
price_usdFloat交易收取的金额(Apple/Google 分成前),以美元计。在 trial_started 中为 null(不收费),除非启用了 Send trial price。
profile_countryString由 Adapty 根据用户画像 IP 地址确定。
profile_event_idUUID唯一事件 ID,可用于去重。
profile_has_access_levelBoolean布尔值,表示该用户画像是否拥有有效的访问等级。
profile_idUUIDAdapty 生成的用户画像 ID,与事件根级别的值相同。
profile_ip_addressString用户画像的 IP 地址(可为 IPv4 或 IPv6,优先使用 IPv4)。若在应用设置中禁用了 Collect users’ IP addresses,则为 null。
profile_total_revenue_usdFloat该用户画像的总收入(已扣除退款金额),以美元计。
promotional_offer_idString所用促销活动的 Adapty ID,由您在看板中创建优惠时设置。
purchase_dateISO 8601 date产品购买的日期和时间。
rate_after_first_yearBoolean布尔值,表示该订阅在连续续订满一年后是否符合降低佣金比例(通常为 15%)的条件。佣金比例因计划资格和国家/地区而异。详见商店佣金与税务。
storeString购买产品的商店。标准值:app_store、play_store、stripe、paddle。
若通过服务端 API 设置了自定义商店交易,则使用 store 参数中的值。
store_countryString应用商店返回的国家/地区信息。
store_offer_categoryString已应用的优惠类别。可能的值为 introductory、promotional、winback。
store_offer_discount_typeString已应用的优惠类型。可能的值为 free_trial、pay_as_you_go 和 pay_up_front。
store_offer_number_of_periodsInteger优惠折扣覆盖的基础计费周期数(1 个或更多)。仅在有优惠时存在。对于 App Store 预付优惠,或商店未报告优惠时长时为 null。
subscription_expires_atISO 8601 date

订阅的到期日期。

在退款、账单问题、宽限期和访问等级相关事件中,该字段保存取消日期或宽限期结束日期(如适用)。在购买和续订事件中,该字段保存订阅的常规到期日期。

transaction_idString交易的唯一标识符。
trial_durationString试用期时长(天)。格式为” days”,例如”7 days”。仅在与试用相关的事件类型中存在:trial_started、trial_converted、trial_cancelled。
variation_idUUID完成购买的付费墙唯一 ID。对于流程,这是流程内付费墙屏幕的 ID,而非 A/B 测试实验变体的 ID。每次发布的流程版本会生成新的屏幕 ID,因此 Adapty 会随时间发送同一实验变体但 variation_id 不同的数据。若需按测试实验变体拆分交易,请使用 ab_test_variant_id。
vendor_product_idString

Apple App Store、Google Play Store 或 Stripe 中的产品 ID。

对于 12 个月承诺方案,值为 <product_id>:monthly。

如果访问权限是在没有真实商店交易的情况下授予的,vendor_product_id 将为以下之一:

  • adapty_server_side_product — 通过服务端 API 授予。
  • adapty_dashboard_product — 在 Adapty 看板中手动授予。
  • adapty_promotion — 旧版。

流程与 A/B 测试字段

流程与 A/B 测试字段用于说明某笔交易来自哪个流程、A/B 测试及实验变体。这些字段适用于所有 A/B 测试类型:常规付费墙和流程 A/B 测试,以及跨版位付费墙和流程 A/B 测试。

Adapty 会在版位交易事件中发送这些字段,即同时携带 developer_id 和 variation_id 的事件。续订、退款、取消及其他订阅事件会沿用原始购买时的流程、A/B 测试和实验变体信息,即使 A/B 测试已结束也是如此。当某个字段没有值时,该字段不会出现在事件中:这些字段永远不会为空字符串或 null。

交易来源flow_id, flow_name, flow_variation_idab_test_idab_test_variant_id, ab_test_variant_nameab_test_parent_name
常规付费墙 A/B 测试—A/B 测试 ID与 variation_id 一致—
非 A/B 测试的付费墙————
流程 A/B 测试✅A/B 测试 ID与 flow_variation_id 一致—
非 A/B 测试的流程✅———
跨版位付费墙 A/B 测试—跨版位测试 ID所有版位共享✅
跨版位流程 A/B 测试✅,使用该版位的流程实验变体跨版位测试 ID所有版位共享✅
非版位来源————

例如,对于跨版位 A/B 测试中流程第二个版位实验变体 A 的购买行为,Adapty 发送:

{
  "variation_id": "<paywall screen ID on this placement>",
  "ab_test_name": "Onboarding test child-1",
  "paywall_name": "scr_a1b2c3d4",
  "flow_id": "<flow ID>",
  "flow_name": "Onboarding X",
  "flow_variation_id": "<variant A on this placement>",
  "ab_test_id": "<crossplacement test ID>",
  "ab_test_variant_id": "<variant A, shared by all placements>",
  "ab_test_variant_name": "A",
  "ab_test_parent_name": "Onboarding test"
}

要基于这些字段构建报告,请按 ID(ab_test_id、ab_test_variant_id、flow_id)对交易进行分组,并将名称用作标签。Adapty 在发送事件时获取名称,因此当你重命名测试、实验变体或流程后,后续事件将使用新名称。已发送的事件不会被重新发送或更新。

Note

跨版位 A/B 测试的共享实验变体 ID 通常只与某一个版位的实验变体 ID 匹配(一般是第一个版位)。若要将事件与 SDK 在特定版位返回的实验变体进行匹配,请使用 flow_variation_id 或 variation_id。

Warning

在跨版位 A/B 测试中,当同一个流程出现在多个实验变体中时,仅凭购买行为无法判断用户属于哪个实验变体。Adapty 会从用户的分配记录中获取实验变体信息。如果该记录不可用,Adapty 将发送 flow_id、flow_name 和 ab_test_id,但不会发送 flow_variation_id、ab_test_variant_id 或 ab_test_variant_name。这种情况发生在以下场景:用户看到流程后立即购买(分配记录尚未保存),以及分配记录过期后发生的续订。Adapty 看板会将此类交易计入第一个实验变体,因此你的集成数据可能与看板数据存在差异。

税费与收入事件的附加属性

以下与税费和收入相关的事件属性是仅适用于特定事件类型的附加字段。这意味着列出的事件类型包含大多数事件类型的事件属性,以及下方列出的额外字段。

具有税费与收入事件属性的事件类型:

  • subscription_renewed
  • subscription_initial_purchase(也称为 subscription_started——同一事件)
  • subscription_refunded
  • non_subscription_purchase
  • non_subscription_purchase_refunded
  • trial_started
  • trial_converted
字段类型描述
net_revenue_localFloat净收入(扣除 Apple/Google 抽成及税费后的收入),以本地货币计。
net_revenue_usdFloat净收入(扣除 Apple/Google 抽成及税费后的收入),以 USD 计。
proceeds_localFloat扣除 Apple/Google 抽成后的 price_local。
proceeds_usdFloat扣除 Apple/Google 抽成后的 price_usd。
tax_amount_localFloatprice_local 中包含的预估税费。Stripe 和 Paddle 始终为 0,即使用户实际缴纳了税费。
tax_amount_usdFloatprice_usd 中包含的预估税费。Stripe 和 Paddle 始终为 0,即使用户实际缴纳了税费。

对于净收入,请直接使用 net_revenue_*。除非 tax_amount_* 为 0,否则 proceeds_* 减去 tax_amount_* 得到的金额会更小。例如,价格为 12、佣金率为 30%、税率为 20% 时,Adapty 的计算方式如下:

  • proceeds_* = price_* × (1 − 佣金率) = 12 × 0.7 = 8.40
  • tax_amount_* = price_* × 税率 ÷ (1 + 税率) = 12 × 0.2 ÷ 1.2 = 2.00
  • net_revenue_* = proceeds_* ÷ (1 + 税率) = 8.40 ÷ 1.2 = 7.00

免费试用不会产生任何费用,因此在 trial_started 事件中,价格字段(price_*、proceeds_*、net_revenue_*、tax_amount_*)和 currency 默认为 null。如需接收这些字段,请在 Webhook 设置中启用 Send trial price。启用后,Adapty 会根据订阅价格乘以 Trial price percentage 计算这些值,并发送 currency。这些值描述的是订阅本身,而非实际扣费,因此统计收入总额时请勿将 trial_started 计入其中。

non_subscription_purchase 示例载荷

non_subscription_purchase 的结构与订阅事件相同,但反映的是一次性或消耗型商品购买。与订阅相关的字段不适用:cancellation_reason、will_renew、is_in_grace_period、is_refund、is_lifetime 和 trial_duration 均不存在。subscription_expires_at 字段存在,但值为 null。税费和收入相关字段(net_revenue_*、proceeds_*、tax_amount_*)均包含在内。

示例 payload(点击展开)
{
  "profile_id": "00000000-0000-0000-0000-000000000000",
  "customer_user_id": "UserIdInYourSystem",
  "event_type": "non_subscription_purchase",
  "event_datetime": "2000-01-31T00:00:00.000000+0000",
  "event_properties": {
    "store": "app_store",
    "currency": "USD",
    "price_usd": 4.99,
    "price_local": 4.99,
    "original_price_usd": 4.99,
    "original_price_local": 4.99,
    "discount_amount_usd": 0,
    "discount_amount_local": 0,
    "proceeds_usd": 4.2415,
    "proceeds_local": 4.2415,
    "net_revenue_usd": 4.2415,
    "net_revenue_local": 4.2415,
    "tax_amount_usd": 0,
    "tax_amount_local": 0,
    "profile_id": "00000000-0000-0000-0000-000000000000",
    "environment": "Production",
    "vendor_product_id": "100coins",
    "transaction_id": "0000000000000000",
    "original_transaction_id": "0000000000000000",
    "purchase_date": "2024-11-15T10:45:36.181000+0000",
    "original_purchase_date": "2024-11-15T10:45:36.181000+0000",
    "subscription_expires_at": null,
    "store_country": "US",
    "profile_country": "US",
    "profile_ip_address": "10.10.1.1",
    "profile_has_access_level": false,
    "profile_total_revenue_usd": 4.99,
    "consecutive_payments": 1,
    "rate_after_first_year": false,
    "profile_event_id": "00000000-0000-0000-0000-000000000000"
  },
  "event_api_version": 1
}

关于访问等级更新事件

Access Level Updated 事件是一种特殊的 Webhook 事件,仅在 Webhook 集成处于活跃状态且该事件类型已启用时才会生成。启用后,该事件将发送至配置的 Webhook,并显示在 Event Feed 中。若未启用,则不会创建该事件。

如果您已启用共享访问等级,则 access level updated 事件将发送至所有共享该访问等级的用户画像。

Tip

使用此事件来更新数据库中用户的访问等级、在后端授予或撤销高级功能,并保持跨设备或跨平台的访问同步。

属性类型描述
ab_test_idUUID交易来源 A/B 测试的 ID。请参阅 流程和 A/B 测试字段。
ab_test_nameString交易来源 A/B 测试的名称。对于跨版位 A/B 测试,为某个版位上的测试名称(<test name> child-N)。
ab_test_parent_nameString跨版位 A/B 测试的名称。仅在跨版位 A/B 测试中存在。
ab_test_variant_idUUID交易来源 A/B 测试实验变体的 ID。
ab_test_variant_nameStringA/B 测试实验变体的名称。
access_level_idString访问等级的 ID。
activated_atISO 8601 date访问权限最近一次激活的日期和时间。
active_introductory_offer_typeString所应用的新用户优惠类型。可能的值为 free_trial、pay_as_you_go 和 pay_up_front。
active_promotional_offer_idString促销活动的 ID,如 Adapty 看板产品部分所示。
active_promotional_offer_typeString所应用的促销活动类型。可能的值为 free_trial、pay_as_you_go 和 pay_up_front。
base_plan_idStringGoogle Play 商店中的基础方案 ID,或 Stripe 中的价格 ID。
billing_issue_detected_atISO 8601 date发生扣款问题的日期和时间。
cancellation_reasonString可能的取消原因:voluntarily_cancelled、billing_error、price_increase、product_was_not_available、refund、cancelled_by_developer、new_subscription_replace、upgraded、unknown、adapty_revoked。
cohort_nameString用户画像所属目标受众的名称。
currencyString本地货币(默认为 USD)。
developer_idString交易来源版位的 ID。
environmentString可能的值为 Sandbox 或 Production。
event_datetimeISO 8601 date事件发生的日期和时间。
expires_atISO 8601 date

访问权限到期的日期和时间。Adapty 根据此字段计算 is_active。

在宽限期内,该字段保存宽限期的结束时间;退款或取消后,保存取消日期。没有单独的宽限期结束字段。

flow_idUUID交易来源流程的 ID。
flow_nameString交易来源流程的名称。
flow_variation_idUUID该版位上流程实验变体的 ID,与 SDK 中的 flow.variationId 相同。
is_activeBoolean表示访问等级是否处于激活状态的布尔值。在生成事件时,根据 expires_at(结合 starts_at 和 is_lifetime)计算得出。
is_in_grace_periodBoolean表示用户画像是否处于宽限期的布尔值。为 true 时,expires_at 保存宽限期的结束时间。
is_lifetimeBoolean表示访问等级是否为永久授权的布尔值。
is_refundBoolean表示该交易是否为退款的布尔值。
original_purchase_dateISO 8601 date对于循环订阅,原始购买是链条中的第一笔交易,其 ID 称为原始交易 ID,用于关联一系列续订;后续交易均为其延伸。原始购买日期即为该第一笔交易的日期和时间。
original_transaction_idString

对于循环订阅,这是关联一系列续订的原始交易 ID。原始交易是链条中的第一笔;后续交易均为其延伸。

如果没有延伸,original_transaction_id 与 store_transaction_id 相同。

原始购买的交易标识符。
paywall_nameString交易来源付费墙的名称。对于流程,为付费墙屏幕的 ID(scr_...)。
paywall_revisionString交易来源付费墙的版本号。默认值为 1。
profile_countryString由 Adapty 根据用户画像 IP 确定。
profile_event_idUUID可用于去重的唯一事件 ID。
profile_has_access_levelBoolean表示用户画像是否拥有有效访问等级的布尔值。
profile_idUUIDAdapty 内部用户画像 ID。
profile_ip_addressString用户画像 IP(可以是 IPv4 或 IPv6,优先使用 IPv4)。如果在应用设置中禁用了 Collect users’ IP addresses,则为 null。
profile_total_revenue_usdFloat用户画像的总收入,含退款。
purchase_dateISO 8601 date产品购买的日期和时间。
renewed_atISO 8601 date当前付费访问周期最近一次开始的日期和时间。在首次续订之前,其值与 activated_at 相同。
starts_atISO 8601 date访问等级开始的日期和时间。
storeString购买产品的商店。标准值:app_store、play_store、stripe、paddle。
如果您通过服务端 API 设置了自定义商店交易,则使用 store 参数中的值。
store_countryString应用商店发送给 Adapty 的国家/地区。
subscription_expires_atISO 8601 date订阅的到期日期。在此事件中,其值与 expires_at 相同:在宽限期内为宽限期结束时间;退款或取消后为取消日期。
transaction_idString交易的唯一标识符。
trial_durationString试用期时长(以天为单位,例如”7 days”)。
variation_idUUID实验变体的标识符,用于将购买归因到对应付费墙。对于流程,为流程内付费墙屏幕的 ID,而非 A/B 测试实验变体的 ID。
vendor_product_idString

商店(Apple/Google/Stripe)中的产品 ID。

对于 12 个月承诺计划,值为 <product_id>:monthly。

如果访问权限是在没有真实商店交易的情况下授予的,vendor_product_id 将为以下之一:

  • adapty_server_side_product — 通过服务端 API 授予。
  • adapty_dashboard_product — 在 Adapty 看板中手动授予。
  • adapty_promotion — 旧版。
will_renewBoolean表示付费访问等级是否将续订。
Warning

请注意,此结构可能会随着时间推移而扩展——我们或我们合作的第三方可能会引入新的数据字段。请确保处理该结构的代码足够健壮,依赖特定字段而非整个结构。