--- title: "Các loại sự kiện và trường dữ liệu webhook" description: "" --- Adapty gửi webhook để phản hồi các sự kiện gói đăng ký. Phần này định nghĩa các loại sự kiện và dữ liệu có trong mỗi webhook. ## Các loại sự kiện Webhook \{#webhook-event-types\} 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](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](set-up-webhook-integration#configure-webhook-integration-in-the-adapty-dashboard). 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ý trả phí không có thời gian dùng thử, tức là bị tính phí ngay lập tức. | | 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ính năng tự động gia hạn gói đăng ký. Người dùng vẫn có thể sử dụng các tính năng cao cấp cho đến khi kết thúc chu kỳ đăng ký đã thanh toán. | | subscription_renewal_reactivated | Kích hoạt khi người dùng bật lại tính năng tự động gia hạn gói đăng ký. | | subscription_expired | Kích hoạt khi gói đăng ký hết hạn 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 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ính năng [tạm dừng gói đăng ký](https://developer.android.com/google/play/billing/lifecycle/subscriptions#pause) (chỉ dành cho Android). | | subscription_deferred | Kích hoạt khi giao dịch mua gói đăng ký được [hoãn lại](https://adapty.io/glossary/subscription-purchase-deferral/), cho phép người dùng trì hoãn việc thanh toán trong khi vẫn duy trì quyền truy cập các tính năng cao cấp. Tính năng này có sẵn thông qua Google Play Developer API và có thể dùng cho các bản dùng thử miễn phí hoặc hỗ trợ người dùng gặp khó khăn về tài chính. | | non_subscription_purchase | Bất kỳ sản phẩm mua một lần nào, 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_converted | Xảy ra khi thời gian 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ó thời gian 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 sẽ được ghi nhận vào ngày 7 tháng 1. | | trial_renewal_cancelled | Người dùng đã tắt tính năng tự động gia hạn trong thời gian dùng thử. Người dùng vẫn có thể sử dụng các tính năng cao cấp cho đến khi thời gian dùng thử kết thúc nhưng sẽ không bị tính phí hay chuyển sang gói đăng ký. | | trial_renewal_reactivated | Xảy ra khi người dùng bật lại tính năng tự động gia hạn trong thời gian dùng thử. | | trial_expired | Kích hoạt khi thời gian dùng thử kết thúc mà không chuyển sang 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ó thể truy cập các tính năng 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 sản phẩm mua một lần đượ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. | :::note `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. ::: ## Cấu trúc sự kiện Webhook \{#webhook-event-structure\} Adapty chỉ gửi những sự kiện mà bạn đã chọn trong phần **Events names** của trang [Integrations -> Webhooks](https://app.adapty.io/integrations/customwebhook). 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](setting-user-attributes#custom-user-attributes) 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: ```json title="Json" showLineNumbers { "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, "base_plan_id": "b1", "developer_id": "onboarding_placement", "ab_test_name": "onboarding_ab_test", "ab_test_revision": 1, "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 \{#event-fields\} 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](webhook-event-types-and-fields#attributions). Được đính kèm nếu **Send Attribution** được bật trong [Webhook settings](https://app.adapty.io/integrations/customwebhook). | | **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](ios-quickstart-identify). 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`. | | **email** | String | Email của người dùng nếu bạn thiết lập bằng phương thức [`updateProfile`](setting-user-attributes) 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](https://www.iso.org/iso-8601-date-and-time-format.html) (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](webhook-event-types-and-fields#event-properties). | | **event_type** | String | Tên sự kiện theo định dạng Adapty. Xem [Loại sự kiện Webhook](webhook-event-types-and-fields#webhook-event-types) để 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](https://app.adapty.io/profiles/users). 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](https://app.adapty.io/profiles/users). | | **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](webhook-event-types-and-fields#play-store-purchase-token), được đính kèm nếu **Send Play Store purchase token** được bật trong [Webhook settings](https://app.adapty.io/integrations/customwebhook). | | **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](how-profiles-work#parent-and-inheritor-profiles). | | **profile_install_datetime** | ISO 8601 | Thời điểm cài đặt theo định dạng [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) (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](general#6-sharing-paid-access-between-user-accounts) 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](https://app.adapty.io/integrations/customwebhook).

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.

| :::note `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 \{#attributions\} Để gửi dữ liệu attribution, hãy bật tùy chọn **Send Attribution** trong trang [Integrations -> Webhooks](https://app.adapty.io/integrations/customwebhook). 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](attribution-integration), 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. ```json title="Json" showLineNumbers { "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 \{#integration-ids\} Các ID tích hợp sau đây hiện được sử dụng trong các sự kiện: - `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` ### Mã token mua hàng trên Play Store \{#play-store-purchase-token\} 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](https://app.adapty.io/integrations/customwebhook). | 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 \{#event-properties\} 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](webhook-event-types-and-fields#for-access-level-updated-event) 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](webhook-event-types-and-fields#additional-tax-and-revenue-event-properties), 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 \{#for-most-event-types\} Các 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ề những sự kiện cụ thể nào. | Trường | Kiểu | Mô tả | |:------------------------------|:--------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **ab_test_name** | String | Tên của [A/B test Adapty](ab-tests) nơi giao dịch phát sinh. | | **ab_test_revision** | Integer | Phiên bản của A/B test nơi giao dịch phát sinh. | | **base_plan_id** | String | [Base plan ID](https://support.google.com/googleplay/android-developer/answer/12154973) trong Google Play Store hoặc [price ID](https://docs.stripe.com/products-prices/how-products-and-prices-work#use-products-and-prices) trong Stripe. | | **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`.

Xuất hiện 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](audience) đã 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 | Đơn vị tiền tệ địa phương. | | **developer_id** | String | ID của [placement](placements) nơi giao dịch phát sinh. | | **environment** | String | Giá trị có thể là `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. | | **original_purchase_date** | ISO 8601 date | Đối với gói đăng ký định kỳ, giao dịch mua ban đầu 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à phần mở rộng của nó. Ngày mua ban đầu là ngày và giờ của giao dịch đầu tiên này. | | **original_transaction_id** | String |

Đối với gói đăng ký định kỳ, đây là original transaction ID liên kết chuỗi gia hạn. Giao dịch ban đầu 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, `original_transaction_id` trùng với store_transaction_id.

| | **paywall_name** | String | Tên của paywall nơi giao dịch phát sinh. | | **paywall_revision** | String | Phiên bản của paywall nơi giao dịch phát sinh. Giá trị mặc định là 1. | | **price_local** | Float | Giá sản phẩm trước khi Apple/Google khấu trừ, tính bằng đơn vị tiền tệ địa phương. | | **price_usd** | Float | Giá sản phẩm trước khi Apple/Google khấu trừ, tính bằng USD. | | **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 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 ra. 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](https://app.adapty.io/settings/general). | | **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](offers) đã được áp 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 áp dụng 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ế](controls-filters-grouping-compare-proceeds#display-gross-or-net-revenue) để biết thêm chi tiết. | | **store** | String | Cửa hàng nơi sản phẩm được mua. Giá trị tiêu 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](api-adapty/operations/setTransaction) bằng server-side API, giá trị từ tham số **store** sẽ được sử dụng. | | **store_country** | String | Quốc gia được app store gửi cho chúng tôi. | | **store_offer_category** | String | Danh mục ưu đãi được áp dụng. Giá trị có thể là `introductory`, `promotional`, `winback`. | | **store_offer_discount_type** | String | Loại ưu đãi được áp dụng. Giá trị có thể là `free_trial`, `pay_as_you_go` và `pay_up_front`. | | **subscription_expires_at** | ISO 8601 date | Ngày hết hạn của gói đăng ký. Thường là trong tương lai. | | **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ỉ xuất hiện 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 thực hiện giao dịch mua. | | **vendor_product_id** | String |

ID sản phẩm trong Apple App Store, Google Play Store hoặc Stripe.

Nếu quyền truy cập được cấp mà không có giao dịch thực từ cửa hàng, `vendor_product_id` sẽ là một trong các giá trị sau:

| #### Thuộc tính sự kiện về thuế và doanh thu bổ sung \{#additional-tax-and-revenue-event-properties\} 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](webhook-event-types-and-fields#for-most-event-types), 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 về thuế và doanh thu: - `subscription_renewed` - `subscription_initial_purchase` (còn được gọi là `subscription_started` — cùng một sự kiện) - `subscription_refunded` - `non_subscription_purchase` | Field | Type | Description | | :-------------------- | :---- | :----------------------------------------------------------- | | **net_revenue_local** | Float | Doanh thu thuần (thu nhập sau khi trừ phần của Apple/Google và thuế) tính theo 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ế) tính theo USD. | | **proceeds_local** | Float | Giá sản phẩm sau khi trừ phần của Apple/Google tính theo tiền tệ địa phương. | | **proceeds_usd** | Float | Giá sản phẩm sau khi trừ phần của Apple/Google. | | **tax_amount_local** | Float | Số tiền thuế bị khấu trừ tính theo tiền tệ địa phương. | | **tax_amount_usd** | Float | Số tiền thuế bị khấu trừ tính theo USD. | #### Ví dụ payload `non_subscription_purchase` \{#non-subscription-purchase-example-payload\} `non_subscription_purchase` có cùng cấu trúc với các sự kiện gói đăng ký nhưng phản ánh một lần mua một lần hoặc consumable. Các trường chỉ dành cho gói đăng ký không áp dụng: `cancellation_reason`, `will_renew`, `is_in_grace_period`, `is_refund`, `is_lifetime`, và `trial_duration` đều không có. `subscription_expires_at` có mặt nhưng là `null`. Các trường thuế và doanh thu (`net_revenue_*`, `proceeds_*`, `tax_amount_*`) được bao gồm.
Ví dụ payload (nhấn để mở rộng) ```json title="Json" showLineNumbers { "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, "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 \{#for-access-level-updated-event\} 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](general#6-sharing-paid-access-between-user-accounts), 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 đó. :::tip 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_name** | String | Tên A/B test nơi giao dịch bắt nguồn. | | **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 lần 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 chỉ định 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 | [Base plan ID](https://support.google.com/googleplay/android-developer/answer/12154973) trong Google Play Store hoặc [price ID](https://docs.stripe.com/products-prices/how-products-and-prices-work#use-products-and-prices) trong Stripe. | | **billing_issue_detected_at** | ISO 8601 date | Ngày và giờ xảy ra sự cố 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 đố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. | | **is_active** | Boolean | Boolean cho biết mức độ truy cập có đang hoạt động hay không. | | **is_in_grace_period** | Boolean | Boolean cho biết hồ sơ người dùng có đang trong thời gian ân hạn hay không. | | **is_lifetime** | Boolean | Boolean cho biết mức độ truy cập có phải là trọn đời hay không. | | **is_refund** | Boolean | Boolean cho biết giao dịch có phải là hoàn tiền hay không. | | **original_purchase_date** | ISO 8601 date | Đối với các gói đăng ký định kỳ, giao dịch mua ban đầu 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à phần mở rộng của nó. Ngày mua ban đầu 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ý định kỳ, đây là original transaction ID liên kết chuỗi gia hạn. Giao dịch ban đầu 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 nào, `original_transaction_id` trùng với store_transaction_id.

Mã định danh giao dịch của lần mua ban đầu. | | **paywall_name** | String | Tên paywall nơi giao dịch bắt nguồn. | | **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 xác định bởi Adapty, 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 trùng lặp. | | **profile_has_access_level** | Boolean | 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 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ó). `null` nếu **Collect users' IP addresses** bị tắt trong [cài đặt ứng dụng](https://app.adapty.io/settings/general). | | **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 quyền truy cập sẽ được gia hạn. | | **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ị tiêu 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](api-adapty/operations/setTransaction) bằng API phía máy chủ, giá trị từ tham số **store** sẽ được sử dụng. | | **store_country** | String | Quốc gia được app store gửi đến Adapty. | | **subscription_expires_at** | ISO 8601 date | Ngày hết hạn của gói đăng ký. | | **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 theo ngày (ví dụ: "7 days"). | | **variation_id** | UUID | Mã định danh của một biến thể, dùng để gán các giao dịch mua cho paywall này. | | **vendor_product_id** | String |

ID sản phẩm trong cửa hàng (Apple/Google/Stripe).

Nếu quyền truy cập được cấp mà không có giao dịch cửa hàng thực, `vendor_product_id` sẽ là một trong các giá trị sau:

| | **will_renew** | Boolean | Cho biết mức độ truy cập trả phí có được gia hạn hay không. | :::warning 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. :::