Các loại sự kiện và trường dữ liệu của webhook
Adapty gửi webhook khi có sự kiện gói đăng ký. Phần này mô tả các loại sự kiện và dữ liệu có trong mỗi webhook.
Các loại sự kiện Webhook
Bạn có thể gửi tất cả các loại sự kiện đến webhook của mình hoặc chỉ chọn một số loại nhất định. Tham khảo Event flows để tìm hiểu loại dữ liệu đầu vào cần mong đợi và cách xây dựng logic nghiệp vụ xung quanh đó. Bạn có thể tắt các loại sự kiện không cần thiết khi thiết lập tích hợp Webhook. Tại đó, bạn cũng có thể thay thế ID sự kiện mặc định của Adapty bằng ID của riêng mình nếu cần.
| Tên sự kiện | Mô tả |
|---|---|
| subscription_started | Kích hoạt khi người dùng bắt đầu gói đăng ký có tính phí mà không có thời gian dùng thử, nghĩa là họ bị tính tiền ngay lập tức. |
| subscription_active | Xác nhận gói đăng ký vẫn còn hoạt động sau sự kiện subscription_started. Bạn cần đặt số ngày giữa thời điểm bắt đầu gói đăng ký và lần kiểm tra này. Sự kiện sẽ được gửi nếu gói đăng ký vẫn còn hoạt động, kể cả khi người dùng đang trong thời gian ân hạn. Nếu gói đăng ký đã kết thúc trước đó, hoặc người dùng đã tắt tự động gia hạn, sự kiện sẽ không được gửi và Adapty sẽ không kiểm tra lại. Sự kiện này chỉ áp dụng cho các gói đăng ký được mua không có dùng thử. Dùng thử được chuyển đổi sẽ gửi trial_converted, và sự kiện đó không bắt đầu việc kiểm tra. |
| subscription_renewed | Xảy ra khi gói đăng ký được gia hạn và người dùng bị tính phí. Sự kiện này bắt đầu từ lần thanh toán thứ hai, dù là gói đăng ký có hay không có dùng thử. |
| subscription_renewal_cancelled | Người dùng đã tắt tự động gia hạn gói đăng ký. Người dùng vẫn được truy cập các tính năng cao cấp cho đến khi kết thúc kỳ đăng ký đã thanh toán. |
| subscription_renewal_reactivated | Kích hoạt khi người dùng bật lại tự động gia hạn gói đăng ký. |
| subscription_expired | Kích hoạt khi gói đăng ký kết thúc hoàn toàn sau khi bị hủy. Ví dụ: nếu người dùng hủy gói đăng ký vào ngày 12 tháng 12 nhưng gói vẫn còn hiệu lực đến ngày 31 tháng 12, sự kiện sẽ được ghi nhận vào ngày 31 tháng 12 khi gói đăng ký hết hạn. |
| subscription_paused | Xảy ra khi người dùng kích hoạt tạm dừng gói đăng ký (chỉ Android). |
| subscription_deferred | Kích hoạt khi bạn gia hạn gói đăng ký của người dùng mà không tính phí: thông qua deferral bằng Google Play Developer API, hoặc gia hạn ngày gia hạn thông qua App Store Server API. Người dùng vẫn được truy cập các tính năng cao cấp cho đến ngày gia hạn được gia hạn. |
| non_subscription_purchase | Bất kỳ giao dịch mua nào không phải gói đăng ký, chẳng hạn như quyền truy cập trọn đời hoặc các sản phẩm consumable như tiền trong game. |
| trial_started | Kích hoạt khi người dùng bắt đầu gói đăng ký dùng thử. |
| trial_active | Xác nhận dùng thử vẫn còn hoạt động sau sự kiện trial_started. Bạn cần đặt số ngày giữa thời điểm bắt đầu dùng thử và lần kiểm tra này. Sự kiện sẽ được gửi nếu dùng thử vẫn đang chạy. Nếu dùng thử đã kết thúc hoặc đã được chuyển đổi trước đó, hoặc người dùng đã tắt tự động gia hạn, sự kiện sẽ không được gửi và Adapty sẽ không kiểm tra lại. |
| trial_converted | Xảy ra khi dùng thử kết thúc và người dùng bị tính phí (lần mua đầu tiên). Ví dụ: nếu người dùng có dùng thử đến ngày 14 tháng 1 nhưng bị tính phí vào ngày 7 tháng 1, sự kiện này sẽ được ghi nhận vào ngày 7 tháng 1. |
| trial_renewal_cancelled | Người dùng đã tắt tự động gia hạn gói đăng ký trong thời gian dùng thử. Người dùng vẫn được truy cập các tính năng cao cấp cho đến khi dùng thử kết thúc nhưng sẽ không bị tính phí hoặc bắt đầu gói đăng ký. |
| trial_renewal_reactivated | Xảy ra khi người dùng bật lại tự động gia hạn gói đăng ký trong thời gian dùng thử. |
| trial_expired | Kích hoạt khi dùng thử kết thúc mà không được chuyển đổi thành gói đăng ký. |
| entered_grace_period | Xảy ra khi một lần thanh toán thất bại và người dùng bước vào thời gian ân hạn (nếu được bật). Người dùng vẫn được truy cập cao cấp trong thời gian này. |
| billing_issue_detected | Kích hoạt khi xảy ra sự cố thanh toán trong quá trình thực hiện giao dịch (ví dụ: số dư thẻ không đủ). |
| subscription_refunded | Kích hoạt khi gói đăng ký được hoàn tiền (ví dụ: do Apple Support xử lý). |
| non_subscription_purchase_refunded | Kích hoạt khi một giao dịch mua không phải gói đăng ký được hoàn tiền. |
| access_level_updated | Xảy ra khi mức độ truy cập của người dùng được cập nhật. |
subscription_renewal_reactivated mang ID sản phẩm trước đó — tức là sản phẩm đang hoạt động khi người dùng hủy — ngay cả khi người dùng sau đó kích hoạt lại bằng cách mua một sản phẩm khác. Apple giữ nguyên original_transaction_id trong toàn bộ chuỗi hủy → kích hoạt lại, vì vậy sự kiện này phản ánh sản phẩm ban đầu. Sản phẩm mới sẽ xuất hiện trong sự kiện subscription_renewed tiếp theo khi việc tính phí cho sản phẩm mới bắt đầu.
Trên Google Play, Adapty có thể gửi sự kiện subscription_started với tất cả các trường tiền tệ được đặt về 0 — ví dụ: khi Google thay thế một gói đăng ký bằng gói khác hoặc khi gói đăng ký bắt đầu với giai đoạn không tính phí. Đừng tính những sự kiện như vậy vào doanh thu. Khi Google thay thế một gói đăng ký, nó sẽ phát hành một purchase token mới, vì vậy Adapty báo cáo giao dịch có thanh toán dưới một store_transaction_id khác.
Cấu trúc sự kiện Webhook
Adapty chỉ gửi những sự kiện mà bạn đã chọn trong phần Events names của trang Integrations -> Webhooks.
Các sự kiện webhook được tuần tự hóa dưới dạng JSON. Phần thân của yêu cầu POST gửi đến máy chủ của bạn sẽ chứa sự kiện đã được tuần tự hóa, được đóng gói trong cấu trúc dưới đây. Tất cả các sự kiện đều có cùng cấu trúc, nhưng các trường dữ liệu sẽ khác nhau tùy theo loại sự kiện, cửa hàng và cấu hình cụ thể của bạn. Thuộc tính người dùng là các thuộc tính người dùng tùy chỉnh mà bạn đã thiết lập, vì vậy chúng chứa những gì bạn đã cấu hình. Các trường dữ liệu attribution cũng giống nhau cho tất cả các loại sự kiện, tuy nhiên danh sách các attribution sẽ phụ thuộc vào nguồn attribution bạn sử dụng trong ứng dụng di động của mình. Xem bên dưới ví dụ về một sự kiện:
{
"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
}
}
Các trường của sự kiện
Các tham số sự kiện đều giống nhau cho tất cả các loại sự kiện.
| Trường | Kiểu | Mô tả |
|---|---|---|
| advertising_id | UUID | ID quảng cáo (chỉ dành cho Android). |
| attributions | JSON | Dữ liệu attribution. Được đính kèm nếu Send Attribution được bật trong Webhook settings. |
| customer_user_id | String | ID người dùng từ app của bạn (UUID, email, hoặc ID khác) nếu bạn đã thiết lập trong code app khi xác định người dùng. Nếu bạn không xác định người dùng trong code app hoặc người dùng cụ thể này là ẩn danh (chưa đăng nhập), trường này sẽ là null. |
| String | Email của người dùng nếu bạn thiết lập bằng phương thức updateProfile trong Adapty SDK hoặc khi tạo/cập nhật hồ sơ người dùng qua server-side API. Nếu bạn không truyền giá trị email vào SDK hoặc phương thức API, trường này sẽ là null. | |
| event_api_version | Integer | Phiên bản Adapty API (hiện tại: 1). |
| event_datetime | ISO 8601 | Thời điểm thực tế (nghiệp vụ) của sự kiện, chẳng hạn ngày mua hàng đối với giao dịch mua hoặc ngày hết hạn đối với sự kiện hết hạn — không phải thời điểm Adapty nhận hoặc gửi sự kiện. Định dạng ISO 8601 (ví dụ: 2020-07-10T15:00:00.000000+0000). Xem ghi chú bên dưới về thứ tự sắp xếp. |
| event_properties | JSON | Thuộc tính sự kiện. |
| event_type | String | Tên sự kiện theo định dạng Adapty. Xem Loại sự kiện Webhook để biết danh sách đầy đủ. |
| idfa | UUID | ID quảng cáo (chỉ dành cho Apple). IDFA trong hồ sơ người dùng trên Adapty Dashboard. Có thể là null nếu không khả dụng do hạn chế theo dõi, chế độ trẻ em, hoặc cài đặt quyền riêng tư. |
| idfv | UUID | Identifier for Vendors (IDFV), duy nhất theo nhà phát triển. IDFV trong hồ sơ người dùng trên Adapty Dashboard. |
| integration_ids | JSON | ID tích hợp người dùng nếu bạn thiết lập bằng phương thức setIntegrationIdentifier trong Adapty SDK hoặc khi tạo/cập nhật hồ sơ người dùng qua server-side API. null nếu không khả dụng hoặc các tích hợp bị tắt. |
| play_store_purchase_token | JSON | Token mua hàng Play Store, được đính kèm nếu Send Play Store purchase token được bật trong Webhook settings. |
| profile_id | UUID | ID hồ sơ người dùng được Adapty tự động tạo cho mỗi hồ sơ. Một Apple/Google ID có thể được liên kết với nhiều profile ID khác nhau nếu bạn không xác định người dùng hoặc cho phép mua hàng trước khi đăng nhập. Tìm hiểu thêm về cách Adapty hoạt động với hồ sơ cha/con. |
| profile_install_datetime | ISO 8601 | Thời điểm cài đặt theo định dạng ISO 8601 (ví dụ: 2020-07-10T15:00:00.000000+0000). |
| profiles_sharing_access_level | JSON | Danh sách người dùng chia sẻ mức độ truy cập ngoại trừ hồ sơ người dùng hiện tại. Nếu tính năng chia sẻ mức độ truy cập được bật cho app của bạn, danh sách này bao gồm các hồ sơ khác đã được sử dụng với cùng Apple/Google ID. Định dạng:
|
| user_agent | String | User-agent trình duyệt của thiết bị. |
| user_attributes | JSON | Dữ liệu tùy chỉnh bạn có thể thiết lập để bổ sung thông tin cụ thể của app vào hồ sơ người dùng. Thường dùng để theo dõi tùy chọn của người dùng (ví dụ: giao diện, ngôn ngữ) hoặc các cờ hành vi (đã hoàn thành onboarding, mức độ sử dụng tính năng). Được định dạng dưới dạng các cặp key-value trong đó key là chuỗi và value có thể là chuỗi hoặc số (ví dụ: {"Favourite_color": "Violet", "Pet_name": "Fluffy"}). Bạn có thể thiết lập thuộc tính tùy chỉnh thủ công trong Adapty Dashboard cho từng hồ sơ người dùng riêng lẻ, theo lập trình bằng phương thức updateProfile trong Adapty SDK, hoặc qua server-side API khi tạo/cập nhật hồ sơ người dùng. Được đính kèm nếu Send User Attributes được bật trong Webhook settings. Trong khi các giá trị thuộc tính tùy chỉnh trong code app di động có thể được thiết lập dưới dạng float hoặc string, các thuộc tính nhận được qua server-side API hoặc import lịch sử có thể có định dạng khác. Trong trường hợp này, các giá trị boolean và integer sẽ được chuyển đổi thành float. |
event_datetime phản ánh thời điểm một sự kiện xảy ra trong vòng đời gói đăng ký, chứ không phải thời điểm Adapty xử lý hay gửi nó. Vì vậy, các sự kiện có thể có cùng event_datetime hoặc đến không theo thứ tự thời gian. Ví dụ, một sự kiện subscription_expired có thể mang event_datetime sớm hơn một sự kiện subscription_renewal_cancelled mà Adapty gửi trước nó. Đừng dựa vào event_datetime để sắp xếp thứ tự các sự kiện. Thay vào đó, hãy sắp xếp sự kiện theo thời gian bạn nhận được, và loại bỏ trùng lặp bằng profile_event_id hoặc các transaction ID.
Attribution
Để gửi dữ liệu attribution, hãy bật tùy chọn Send Attribution trong trang Integrations -> Webhooks. Nếu bạn đã bật tính năng gửi dữ liệu attribution và đã thiết lập tích hợp attribution, dữ liệu dưới đây sẽ được gửi kèm theo sự kiện cho mỗi nguồn. Cùng một dữ liệu attribution sẽ được gửi cho tất cả các loại sự kiện.
{
"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"
}
}
}
| Tên trường | Kiểu dữ liệu | Mô tả |
|---|---|---|
| ad_set | String | Ad set attribution. |
| status | String | Có thể là organic, non_organic, hoặc unknown. |
| channel | String | Tên kênh marketing. |
| ad_group | String | Ad group attribution. |
| campaign | String | Tên chiến dịch marketing. |
| creative | String | Từ khóa creative của attribution. |
| created_at | ISO 8601 date | Ngày và giờ tạo bản ghi attribution. |
| network_user_id | String | ID được nguồn attribution gán cho người dùng. |
ID tích hợp
Các ID tích hợp sau đây hiện được sử dụng trong các sự kiện:
adjust_device_idairbridge_device_idamplitude_device_idamplitude_user_idappmetrica_device_idappmetrica_profile_idappsflyer_idbranch_idfacebook_anonymous_idfirebase_app_instance_idmixpanel_user_idpushwoosh_hwidone_signal_player_idone_signal_subscription_idtenjin_analytics_installation_idposthog_distinct_user_idsingular_sdid
Mã token mua hàng trên Play Store
Trường này chứa toàn bộ dữ liệu cần thiết để xác thực lại giao dịch khi cần. Nó chỉ được gửi khi tùy chọn Send Play Store purchase token được bật trong cài đặt tích hợp Webhook.
| Field | Type | Description |
|---|---|---|
| product_id | String | Mã định danh duy nhất của sản phẩm (SKU) được mua trên Play Store. |
| purchase_token | String | Token do Google Play tạo ra để xác định duy nhất giao dịch mua này. |
| is_subscription | Boolean | Cho biết sản phẩm được mua là gói đăng ký (true) hay sản phẩm mua một lần (false). |
Thuộc tính sự kiện
Thuộc tính sự kiện có thể khác nhau tùy theo loại sự kiện và thậm chí giữa các sự kiện cùng loại. Ví dụ, một sự kiện từ App Store sẽ không bao gồm các thuộc tính dành riêng cho Android như base_plan_id.
Sự kiện Access Level Updated có các thuộc tính riêng biệt, vì vậy chúng tôi đã dành một mục riêng cho nó. Tương tự, chúng tôi cũng tách riêng Thuộc tính sự kiện thuế và doanh thu bổ sung, vì chúng chỉ áp dụng cho một số loại sự kiện nhất định.
Đối với hầu hết các loại sự kiện
Thuộc tính sự kiện của hầu hết các loại sự kiện đều nhất quán (ngoại trừ sự kiện Access Level Updated, được mô tả trong phần riêng của nó). Dưới đây là bảng tổng hợp các thuộc tính và chỉ rõ chúng thuộc về sự kiện cụ thể nào.
Adapty chuyển đổi các loại tiền tệ khác sang USD theo tỷ giá của currencylayer.com (cập nhật mỗi 8 giờ). Tỷ giá được cố định tại thời điểm giao dịch — các thay đổi sau đó không ảnh hưởng đến kết quả chuyển đổi.
| Trường | Kiểu | Mô tả |
|---|---|---|
| ab_test_id | UUID | ID của A/B test Adapty nơi giao dịch bắt nguồn. Với A/B test đa placement, đây là ID của test đa placement, giống nhau trên mọi placement. Xem Các trường Flow và A/B test. |
| ab_test_name | String | Tên của A/B test Adapty nơi giao dịch bắt nguồn. Với A/B test đa placement, đây là tên của test trên một placement, theo định dạng <test name> child-N, trong đó N là số thứ tự của placement, không phải biến thể. Để nhóm A/B test đa placement theo các placement, hãy dùng ab_test_id và lấy tên từ ab_test_parent_name. |
| ab_test_parent_name | String | Tên của A/B test đa placement nơi giao dịch bắt nguồn. Chỉ có với các A/B test đa placement. |
| ab_test_revision | Integer | Revision của A/B test nơi giao dịch bắt nguồn. |
| ab_test_variant_id | UUID | ID của biến thể A/B test nơi giao dịch bắt nguồn. Trong A/B test paywall thông thường, giá trị này khớp với variation_id. Trong A/B test flow, khớp với flow_variation_id. Trong A/B test đa placement, giá trị này giống nhau cho biến thể trên mọi placement. Dùng để phân tách giao dịch theo biến thể của test. |
| ab_test_variant_name | String | Tên của biến thể A/B test. Với A/B test đa placement, đây là tên biến thể từ cài đặt test. Với các test khác, đây là tên biến thể, hoặc tên paywall hay flow khi biến thể không có tên. Xuất hiện cùng với ab_test_variant_id. |
| base_plan_id | String | ID gói cơ bản trên Google Play Store hoặc ID giá trên Stripe. |
| cancellation_reason | String | Các lý do hủy có thể có: Có trong các loại sự kiện sau: subscription_cancelled, subscription_refunded và trial_cancelled. |
| cohort_name | String | Tên của đối tượng đã xác định paywall nào được hiển thị cho người dùng. |
| consecutive_payments | Integer | Số kỳ mà người dùng đã đăng ký liên tục không gián đoạn. Bao gồm kỳ hiện tại. |
| currency | String | Tiền tệ địa phương. null trong trial_started trừ khi Send trial price được bật. Xem Thuộc tính sự kiện thuế và doanh thu bổ sung. |
| developer_id | String | ID của placement nơi giao dịch bắt nguồn. |
| discount_amount_local | Float | Chiết khấu áp dụng cho giao dịch: giá tiêu chuẩn trừ đi số tiền thực tế được tính, trước khi Apple/Google khấu trừ, tính theo tiền tệ địa phương. 0 cho giao dịch mua giá đầy đủ. Với dùng thử miễn phí, bằng với giá tiêu chuẩn đầy đủ (original_price_local), vì không thu phí gì. null khi có ưu đãi áp dụng nhưng giá tiêu chuẩn không xác định (xem original_price_local). Luôn là null với ưu đãi trả trước (pay-up-front) của App Store: khoản thanh toán trả trước một lần bao gồm nhiều kỳ thanh toán nên không thể so sánh với giá tiêu chuẩn theo kỳ. |
| discount_amount_usd | Float | Giá trị của discount_amount_local tính bằng USD. |
| environment | String | Các giá trị có thể có: Sandbox hoặc Production. |
| event_datetime | ISO 8601 date | Ngày và giờ của sự kiện. Giống với giá trị ở cấp gốc của sự kiện. |
| flow_id | UUID | ID của flow nơi giao dịch bắt nguồn. Có trong mọi giao dịch thực hiện trong flow, dù có A/B test hay không. |
| flow_name | String | Tên của flow nơi giao dịch bắt nguồn. Xuất hiện cùng với flow_id. |
| flow_variation_id | UUID | ID của biến thể flow trên placement này. Giá trị này giống với giá trị SDK trả về cho ứng dụng dưới dạng flow.variationId. Xuất hiện cùng với flow_id. |
| original_price_local | Float | Giá tiêu chuẩn không chiết khấu của sản phẩm trước khi Apple/Google khấu trừ, tính theo tiền tệ địa phương. Với gói đăng ký, đây là giá gia hạn. Bằng price_local khi mua giá đầy đủ và luôn bằng price_local với sản phẩm mua một lần, vì cửa hàng không báo cáo giá tiêu chuẩn riêng cho các sản phẩm này. null với giao dịch có chiết khấu khi cửa hàng không báo cáo giá tiêu chuẩn đáng tin cậy (ví dụ: tự động gia hạn đang tắt, lần gia hạn vẫn còn ưu đãi, hoặc đang chờ thay đổi sản phẩm). |
| original_price_usd | Float | Giống original_price_local, tính bằng USD. |
| original_purchase_date | ISO 8601 date | Với các gói đăng ký định kỳ, giao dịch mua gốc là giao dịch đầu tiên trong chuỗi, ID của nó gọi là original transaction ID liên kết chuỗi gia hạn; các giao dịch sau là phần mở rộng của nó. Ngày mua gốc là ngày và giờ của giao dịch đầu tiên này. |
| original_transaction_id | String | Với các gói đăng ký định kỳ, đây là original transaction ID liên kết chuỗi gia hạn. Giao dịch gốc là giao dịch đầu tiên trong chuỗi; các giao dịch sau là phần mở rộng của nó. Nếu không có phần mở rộng, |
| paywall_name | String | Tên của paywall nơi giao dịch bắt nguồn. Với flow, đây là ID của màn hình paywall bên trong flow (scr_...), không phải tên. Tên flow nằm trong flow_name. |
| paywall_revision | String | Revision của paywall nơi giao dịch bắt nguồn. Giá trị mặc định là 1. |
| price_local | Float | Số tiền tính cho giao dịch trước khi Apple/Google khấu trừ, tính theo tiền tệ địa phương. null trong trial_started, vì không thu phí gì, trừ khi Send trial price được bật. |
| price_usd | Float | Số tiền tính cho giao dịch trước khi Apple/Google khấu trừ, tính bằng USD. null trong trial_started, vì không thu phí gì, trừ khi Send trial price được bật. |
| profile_country | String | Được Adapty xác định dựa trên IP của hồ sơ người dùng. |
| profile_event_id | UUID | ID sự kiện duy nhất có thể dùng để khử trùng lặp. |
| profile_has_access_level | Boolean | Giá trị boolean cho biết hồ sơ người dùng có mức độ truy cập đang hoạt động hay không. |
| profile_id | UUID | ID hồ sơ người dùng do Adapty tạo. Giống với giá trị ở cấp gốc của sự kiện. |
| profile_ip_address | String | IP của hồ sơ người dùng (có thể là IPv4 hoặc IPv6, ưu tiên IPv4 khi có). null nếu Collect users’ IP addresses bị tắt trong cài đặt ứng dụng. |
| profile_total_revenue_usd | Float | Tổng doanh thu của hồ sơ người dùng sau khi trừ các khoản hoàn tiền. |
| promotional_offer_id | String | ID Adapty của ưu đãi được sử dụng. Bạn đặt ID này khi tạo ưu đãi trong dashboard. |
| purchase_date | ISO 8601 date | Ngày và giờ mua sản phẩm. |
| rate_after_first_year | Boolean | Boolean cho biết gói đăng ký đủ điều kiện nhận mức hoa hồng giảm (thường là 15%) sau một năm gia hạn liên tục. Mức hoa hồng thay đổi tùy theo điều kiện tham gia chương trình và quốc gia. Xem Hoa hồng cửa hàng và thuế để biết thêm chi tiết. |
| store | String | Cửa hàng nơi sản phẩm được mua. Các giá trị tiêu chuẩn: app_store, play_store, stripe, paddle. Nếu bạn đặt giao dịch cửa hàng tùy chỉnh bằng API phía server, giá trị từ tham số store sẽ được sử dụng. |
| store_country | String | Quốc gia được cửa hàng ứng dụng gửi cho chúng tôi. |
| store_offer_category | String | Danh mục ưu đãi được áp dụng. Các giá trị có thể có: introductory, promotional, winback. |
| store_offer_discount_type | String | Loại ưu đãi được áp dụng. Các giá trị có thể có: free_trial, pay_as_you_go và pay_up_front. |
| store_offer_number_of_periods | Integer | Số kỳ thanh toán cơ bản mà ưu đãi chiết khấu (1 hoặc nhiều hơn). Chỉ có khi có ưu đãi áp dụng. null với ưu đãi trả trước (pay-up-front) của App Store và khi cửa hàng không báo cáo thời hạn ưu đãi. |
| subscription_expires_at | ISO 8601 date | Ngày hết hạn của gói đăng ký. Trong các sự kiện hoàn tiền, lỗi thanh toán, thời gian ân hạn và mức độ truy cập, trường này chứa ngày hủy hoặc ngày kết thúc thời gian ân hạn khi có áp dụng. Trong các sự kiện mua và gia hạn, trường này chứa ngày hết hạn gói đăng ký thông thường. |
| transaction_id | String | Mã định danh duy nhất cho một giao dịch. |
| trial_duration | String | Thời hạn của giai đoạn dùng thử tính bằng ngày. Được gửi theo định dạng ” days”, ví dụ “7 days”. Chỉ có trong các loại sự kiện liên quan đến dùng thử: trial_started, trial_converted, trial_cancelled. |
| variation_id | UUID | ID duy nhất của paywall nơi giao dịch mua được thực hiện. Với flow, đây là ID của màn hình paywall bên trong flow, không phải biến thể A/B test. Mỗi phiên bản flow được xuất bản sẽ có ID màn hình mới, vì vậy Adapty gửi một biến thể với các giá trị variation_id khác nhau theo thời gian. Để phân tách giao dịch theo biến thể test, hãy dùng ab_test_variant_id. |
| vendor_product_id | String | ID sản phẩm trên Apple App Store, Google Play Store hoặc Stripe. Với gói cam kết 12 tháng, giá trị là Nếu quyền truy cập được cấp mà không có giao dịch cửa hàng thực tế,
|
Trường flow và A/B test
Các trường flow và A/B test cho bạn biết transaction đến từ flow, A/B test và biến thể nào. Chúng hoạt động với mọi loại A/B test: A/B test paywall và flow thông thường, cũng như A/B test crossplacement trên paywall và flow.
Adapty gửi các trường này trong các sự kiện của giao dịch được thực hiện trên một placement, cùng với các sự kiện mang developer_id và variation_id. Các sự kiện gia hạn, hoàn tiền, hủy đăng ký và các sự kiện gói đăng ký khác đều mang cùng flow, A/B test và biến thể như lần mua ban đầu, ngay cả sau khi A/B test kết thúc. Khi một trường không có giá trị, sự kiện sẽ không bao gồm trường đó: các trường này không bao giờ rỗng hoặc là null.
| Nguồn giao dịch | flow_id, flow_name, flow_variation_id | ab_test_id | ab_test_variant_id, ab_test_variant_name | ab_test_parent_name |
|---|---|---|---|---|
| A/B test paywall thông thường | — | ID A/B test | Khớp với variation_id | — |
| Paywall ngoài A/B test | — | — | — | — |
| A/B test flow | ✅ | ID A/B test | Khớp với flow_variation_id | — |
| Flow ngoài A/B test | ✅ | — | — | — |
| A/B test đa placement trên paywall | — | ID test đa placement | Dùng chung cho tất cả placement | ✅ |
| A/B test đa placement trên flow | ✅, với biến thể flow tại placement này | ID test đa placement | Dùng chung cho tất cả placement | ✅ |
| Không phải placement | — | — | — | — |
Ví dụ, đối với một giao dịch mua trong biến thể A ở placement thứ hai của A/B test xuyên placement trên flow, Adapty gửi:
{
"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"
}
Để xây dựng báo cáo dựa trên các trường này, hãy nhóm các giao dịch theo ID (ab_test_id, ab_test_variant_id, flow_id) và dùng tên làm nhãn. Adapty lấy tên tại thời điểm gửi sự kiện, vì vậy sau khi bạn đổi tên một A/B test, biến thể hoặc flow, các sự kiện sau đó sẽ mang tên mới. Các sự kiện đã gửi sẽ không được gửi lại hoặc cập nhật.
ID biến thể chung của một A/B test nhiều placement chỉ khớp với ID biến thể trên một placement duy nhất, thường là placement đầu tiên. Để so khớp một sự kiện với biến thể mà SDK trả về trên một placement cụ thể, hãy dùng flow_variation_id hoặc variation_id.
Trong một A/B test đa placement mà cùng một flow xuất hiện ở nhiều hơn một biến thể, chỉ riêng giao dịch mua không thể xác định được người dùng thuộc biến thể nào. Adapty sẽ lấy thông tin biến thể từ bản ghi phân công của người dùng. Nếu bản ghi đó không khả dụng, Adapty sẽ gửi flow_id, flow_name, và ab_test_id, nhưng không gửi flow_variation_id, ab_test_variant_id, hay ab_test_variant_name. Điều này xảy ra khi người dùng mua ngay sau khi xem flow, trước khi bản ghi được lưu, và với các lần gia hạn diễn ra sau khi bản ghi hết hạn. Adapty Dashboard tính các giao dịch như vậy vào biến thể đầu tiên, vì vậy dữ liệu tích hợp của bạn có thể khác với dashboard.
Thuộc tính sự kiện thuế và doanh thu bổ sung
Các thuộc tính sự kiện liên quan đến thuế và doanh thu dưới đây là các trường bổ sung chỉ áp dụng cho một số loại sự kiện nhất định. Điều này có nghĩa là các loại sự kiện được liệt kê bao gồm Thuộc tính sự kiện cho hầu hết các loại sự kiện, cùng với các trường bổ sung được liệt kê bên dưới.
Các loại sự kiện có thuộc tính sự kiện thuế và doanh thu:
subscription_renewedsubscription_initial_purchase(còn được gọi làsubscription_started— cùng một sự kiện)subscription_refundednon_subscription_purchasenon_subscription_purchase_refundedtrial_startedtrial_converted
| Trường | Kiểu | Mô tả |
|---|---|---|
| net_revenue_local | Float | Doanh thu thuần (thu nhập sau khi trừ phần của Apple/Google và thuế) theo đơn vị tiền tệ địa phương. |
| net_revenue_usd | Float | Doanh thu thuần (thu nhập sau khi trừ phần của Apple/Google và thuế) theo USD. |
| proceeds_local | Float | price_local sau khi trừ phần của Apple/Google. |
| proceeds_usd | Float | price_usd sau khi trừ phần của Apple/Google. |
| tax_amount_local | Float | Thuế ước tính được bao gồm trong price_local. 0 đối với Stripe và Paddle, ngay cả khi người dùng đã trả thuế. |
| tax_amount_usd | Float | Thuế ước tính được bao gồm trong price_usd. 0 đối với Stripe và Paddle, ngay cả khi người dùng đã trả thuế. |
Đối với doanh thu ròng, hãy sử dụng trực tiếp net_revenue_*. Trừ khi tax_amount_* bằng 0, proceeds_* trừ tax_amount_* sẽ cho ra một con số nhỏ hơn. Ví dụ: với giá 12, hoa hồng 30% và thuế suất 20%, Adapty tính như sau:
proceeds_*=price_*× (1 − commission) = 12 × 0.7 = 8.40tax_amount_*=price_*× tax rate ÷ (1 + tax rate) = 12 × 0.2 ÷ 1.2 = 2.00net_revenue_*=proceeds_*÷ (1 + tax rate) = 8.40 ÷ 1.2 = 7.00
Thử nghiệm miễn phí không tính phí, vì vậy trong trial_started các trường giá (price_*, proceeds_*, net_revenue_*, tax_amount_*) và currency mặc định là null. Để nhận chúng, hãy bật Send trial price trong cài đặt webhook. Adapty sẽ tính toán chúng dựa trên giá gói đăng ký nhân với Trial price percentage, và gửi currency. Các giá trị này mô tả gói đăng ký, không phải khoản tính phí, vì vậy không tính trial_started vào tổng doanh thu.
Ví dụ payload non_subscription_purchase
non_subscription_purchase có cấu trúc tương tự sự kiện gói đăng ký nhưng phản ánh sản phẩm mua một lần hoặc consumable. Các trường chỉ áp dụng cho gói đăng ký sẽ không có mặt: cancellation_reason, will_renew, is_in_grace_period, is_refund, is_lifetime, và trial_duration. subscription_expires_at có mặt nhưng có giá trị null. Các trường thuế và doanh thu (net_revenue_*, proceeds_*, tax_amount_*) được bao gồm đầy đủ.
Ví dụ payload (nhấn để mở rộng)
{
"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
} Đối với sự kiện Access Level Updated
Sự kiện Access Level Updated là một loại sự kiện webhook đặc biệt, chỉ được tạo ra khi tích hợp Webhook đang hoạt động và loại sự kiện này được bật. Nếu được bật, sự kiện sẽ được gửi đến Webhook đã cấu hình và hiển thị trong Event Feed. Nếu không được bật, sự kiện sẽ không được tạo.
Nếu bạn đã bật chia sẻ mức độ truy cập, sự kiện access level updated sẽ được gửi cho tất cả các hồ sơ người dùng đang chia sẻ mức độ truy cập đó.
Sử dụng sự kiện này để cập nhật mức độ truy cập của người dùng trong cơ sở dữ liệu, cấp hoặc thu hồi các tính năng cao cấp trên backend, và đồng bộ quyền truy cập trên các thiết bị hoặc nền tảng khác nhau.
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
| ab_test_id | UUID | ID của A/B test nơi giao dịch bắt nguồn. Xem Các trường của flow và A/B test. |
| ab_test_name | String | Tên của A/B test nơi giao dịch bắt nguồn. Đối với A/B test đa placement, là tên của test trên một placement (<tên test> child-N). |
| ab_test_parent_name | String | Tên của A/B test đa placement. Chỉ có mặt trong các A/B test đa placement. |
| ab_test_variant_id | UUID | ID của biến thể A/B test nơi giao dịch bắt nguồn. |
| ab_test_variant_name | String | Tên của biến thể A/B test. |
| access_level_id | String | ID của mức độ truy cập. |
| activated_at | ISO 8601 date | Ngày và giờ khi quyền truy cập được kích hoạt gần nhất. |
| active_introductory_offer_type | String | Loại ưu đãi giới thiệu được áp dụng. Các giá trị có thể là free_trial, pay_as_you_go và pay_up_front. |
| active_promotional_offer_id | String | ID của ưu đãi như được ghi trong phần Product của Adapty Dashboard. |
| active_promotional_offer_type | String | Loại ưu đãi được áp dụng. Các giá trị có thể là free_trial, pay_as_you_go và pay_up_front. |
| base_plan_id | String | ID base plan trong Google Play Store hoặc price ID trong Stripe. |
| billing_issue_detected_at | ISO 8601 date | Ngày và giờ phát sinh vấn đề thanh toán. |
| cancellation_reason | String | Các lý do hủy có thể có: voluntarily_cancelled, billing_error, price_increase, product_was_not_available, refund, cancelled_by_developer, new_subscription_replace, upgraded, unknown, adapty_revoked. |
| cohort_name | String | Tên của đối tượng mà hồ sơ người dùng thuộc về. |
| currency | String | Đơn vị tiền tệ địa phương (mặc định là USD). |
| developer_id | String | ID của placement nơi giao dịch bắt nguồn. |
| environment | String | Các giá trị có thể là Sandbox hoặc Production. |
| event_datetime | ISO 8601 date | Ngày và giờ của sự kiện. |
| expires_at | ISO 8601 date | Ngày và giờ khi quyền truy cập hết hạn. Adapty tính toán Trong thời gian ân hạn, trường này chứa thời điểm kết thúc thời gian ân hạn; sau khi hoàn tiền hoặc hủy, trường này chứa ngày hủy. Không có trường riêng cho thời điểm kết thúc thời gian ân hạn. |
| flow_id | UUID | ID của flow nơi giao dịch bắt nguồn. |
| flow_name | String | Tên của flow nơi giao dịch bắt nguồn. |
| flow_variation_id | UUID | ID của biến thể flow trên placement này, giống với flow.variationId trong SDK. |
| is_active | Boolean | Giá trị boolean cho biết mức độ truy cập có đang hoạt động không. Được tính từ expires_at (cùng với starts_at và is_lifetime) khi sự kiện được tạo. |
| is_in_grace_period | Boolean | Giá trị boolean cho biết hồ sơ người dùng có đang trong thời gian ân hạn không. Khi true, expires_at chứa thời điểm kết thúc thời gian ân hạn. |
| is_lifetime | Boolean | Giá trị boolean cho biết mức độ truy cập có phải là trọn đời không. |
| is_refund | Boolean | Giá trị boolean cho biết giao dịch có phải là hoàn tiền không. |
| original_purchase_date | ISO 8601 date | Đối với các gói đăng ký tự động gia hạn, giao dịch gốc là giao dịch đầu tiên trong chuỗi, ID của nó được gọi là original transaction ID liên kết chuỗi gia hạn; các giao dịch sau là sự mở rộng của nó. Ngày mua gốc là ngày và giờ của giao dịch đầu tiên này. |
| original_transaction_id | String | Đối với các gói đăng ký tự động gia hạn, đây là original transaction ID liên kết chuỗi gia hạn. Giao dịch gốc là giao dịch đầu tiên trong chuỗi; các giao dịch sau là sự mở rộng của nó. Nếu không có giao dịch mở rộng, |
| paywall_name | String | Tên của paywall nơi giao dịch bắt nguồn. Đối với một flow, là ID của màn hình paywall (scr_...). |
| paywall_revision | String | Phiên bản của paywall nơi giao dịch bắt nguồn. Giá trị mặc định là 1. |
| profile_country | String | Được Adapty xác định dựa trên IP của hồ sơ người dùng. |
| profile_event_id | UUID | ID sự kiện duy nhất có thể dùng để loại bỏ trùng lặp. |
| profile_has_access_level | Boolean | Giá trị boolean cho biết hồ sơ người dùng có mức độ truy cập đang hoạt động không. |
| profile_id | UUID | ID hồ sơ người dùng nội bộ của Adapty. |
| profile_ip_address | String | IP của hồ sơ người dùng (có thể là IPv4 hoặc IPv6, ưu tiên IPv4 khi có). Giá trị null nếu Collect users’ IP addresses bị tắt trong cài đặt ứng dụng. |
| profile_total_revenue_usd | Float | Tổng doanh thu của hồ sơ người dùng, bao gồm cả hoàn tiền. |
| purchase_date | ISO 8601 date | Ngày và giờ mua sản phẩm. |
| renewed_at | ISO 8601 date | Ngày và giờ khi kỳ truy cập có phí hiện tại bắt đầu gần nhất. Cho đến lần gia hạn đầu tiên, giá trị này trùng với activated_at. |
| starts_at | ISO 8601 date | Ngày và giờ khi mức độ truy cập bắt đầu. |
| store | String | Cửa hàng nơi sản phẩm được mua. Các giá trị chuẩn: app_store, play_store, stripe, paddle. Nếu bạn thiết lập giao dịch cửa hàng tùy chỉnh bằng server-side API, giá trị từ tham số store sẽ được sử dụng. |
| store_country | String | Quốc gia được cửa hàng ứng dụng gửi đến Adapty. |
| subscription_expires_at | ISO 8601 date | Ngày hết hạn của gói đăng ký. Trong sự kiện này, giá trị giống với expires_at: trong thời gian ân hạn là thời điểm kết thúc thời gian ân hạn; sau khi hoàn tiền hoặc hủy là ngày hủy. |
| transaction_id | String | Mã định danh duy nhất cho một giao dịch. |
| trial_duration | String | Thời hạn của thời gian dùng thử tính bằng ngày (ví dụ: “7 days”). |
| variation_id | UUID | Mã định danh của một biến thể, dùng để quy kết các giao dịch mua cho paywall này. Đối với một flow, là ID của màn hình paywall bên trong flow, không phải biến thể A/B test. |
| vendor_product_id | String | ID sản phẩm trong cửa hàng (Apple/Google/Stripe). Đối với gói cam kết 12 tháng, giá trị là Nếu quyền truy cập được cấp mà không có giao dịch cửa hàng thực,
|
| will_renew | Boolean | Cho biết mức độ truy cập có phí có được gia hạn không. |
Lưu ý rằng cấu trúc này có thể mở rộng theo thời gian — với dữ liệu mới được chúng tôi hoặc các bên thứ ba mà chúng tôi hợp tác giới thiệu. Hãy đảm bảo rằng code xử lý cấu trúc này đủ linh hoạt và chỉ phụ thuộc vào các trường cụ thể thay vì toàn bộ cấu trúc.