Các loại sự kiện và trường dữ liệu webhook

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

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ý 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ý (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, 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.

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

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_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

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`.
email	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: profile_id: (UUID) Adapty ID customer_user_id: (String) Customer User ID nếu được cung cấp
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_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

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á hối đoái từ currencylayer.com (cập nhật mỗi 8 giờ). Tỷ giá được cố định tại thời điểm giao dịch — những thay đổi sau đó không ảnh hưởng đến kết quả chuyển đổi.

Trường	Kiểu	Mô tả
ab_test_name	String	Tên của A/B test trên Adapty mà giao dịch bắt nguồn từ đó.
ab_test_revision	Integer	Phiên bản của A/B test mà giao dịch bắt nguồn từ đó.
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ó: `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 đã 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 bị 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 mà giao dịch bắt nguồn từ đó.
discount_amount_local	Float	Mức 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ừ phần của họ, tính theo tiền tệ địa phương. `0` với giao dịch mua giá đầy đủ. Với bản dùng thử miễn phí, bằng giá tiêu chuẩn đầy đủ (`original_price_local`) vì không tính phí gì. `null` khi có ưu đãi áp dụng nhưng không biết giá tiêu chuẩn (xem `original_price_local`). Luôn là `null` với ưu đãi trả trước một lần 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 theo USD.
environment	String	Các giá trị có thể có là `Sandbox` hoặc `Production`.
event_datetime	ISO 8601 date	Ngày và giờ xảy ra sự kiện. Giống với giá trị ở cấp gốc của sự kiện.
original_price_local	Float	Giá tiêu chuẩn, chưa chiết khấu của sản phẩm trước khi Apple/Google khấu trừ phần của họ, 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` với giao dịch 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 chúng. `null` với giao dịch mua 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ự gia hạn bị tắt, lần gia hạn vẫn có ưu đãi, hoặc đang chờ thay đổi sản phẩm).
original_price_usd	Float	Giống `original_price_local`, tính theo USD.
original_purchase_date	ISO 8601 date	Với gói đăng ký tự động gia hạn, giao dịch mua 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à 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 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à 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 mà giao dịch bắt nguồn từ đó.
paywall_revision	String	Phiên bản của paywall mà giao dịch bắt nguồn từ đó. Giá trị mặc định là 1.
price_local	Float	Số tiền được tính cho giao dịch trước khi Apple/Google khấu trừ phần của họ, tính theo tiền tệ địa phương. `null` với bản dùng thử miễn phí vì không tính phí gì.
price_usd	Float	Số tiền được tính cho giao dịch trước khi Apple/Google khấu trừ phần của họ, tính theo USD. `null` với bản dùng thử miễn phí vì không tính phí gì.
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.
profile_total_revenue_usd	Float	Tổng doanh thu của hồ sơ người dùng sau khi đã trừ đi 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 để được giảm tỷ lệ hoa hồng (thường là 15%) sau một năm gia hạn liên tục. Tỷ lệ hoa hồng thay đổi tùy theo điều kiện 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 thiết lập giao dịch cửa hàng tùy chỉnh qua API phía máy chủ, giá trị từ tham số store sẽ được sử dụng.
store_country	String	Quốc gia do 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ó là `introductory`, `promotional`, `winback`.
store_offer_discount_type	String	Loại ưu đãi được áp dụng. Các giá trị có thể có là `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 kỳ trở lên). Chỉ xuất hiện khi có ưu đãi áp dụng. `null` với ưu đãi trả trước một lần 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ý. Thường là trong tương lai.
transaction_id	String	Mã định danh duy nhất của 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 trên 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 cửa hàng thực, `vendor_product_id` sẽ là một trong các giá trị: `adapty_server_side_product` — được cấp qua API phía máy chủ. `adapty_dashboard_product` — được cấp thủ công trong Adapty Dashboard. `adapty_promotion` — phiên bản cũ.

Thuộc tính sự kiện về 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 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 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)

{
  "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_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 trong Google Play Store hoặc price ID 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.
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 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: `adapty_server_side_product` — được cấp qua API phía máy chủ. `adapty_dashboard_product` — được cấp thủ công trong Adapty Dashboard. `adapty_promotion` — cũ.
will_renew	Boolean	Cho biết mức độ truy cập trả phí có được gia hạn hay 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.

Các loại sự kiện và trường dữ liệu webhook

Các loại sự kiện Webhook

Cấu trúc sự kiện Webhook

Các trường của sự kiện

Attribution

ID tích hợp

Mã token mua hàng trên Play Store

Thuộc tính sự kiện

Đối với hầu hết các loại sự kiện

Thuộc tính sự kiện về thuế và doanh thu bổ sung

Ví dụ payload non_subscription_purchase

Đối với sự kiện Access Level Updated

Ví dụ payload `non_subscription_purchase`