AppsFlyer

Adapty trao đổi dữ liệu với AppsFlyer theo cả hai chiều. AppsFlyer cho Adapty biết chiến dịch nào đã mang lại từng người dùng. Adapty cho AppsFlyer biết người dùng đó đã chi trả bao nhiêu — các giao dịch mua, gia hạn, dùng thử và hoàn tiền, kèm theo doanh thu và thông tin chi tiết về sản phẩm.

• Xem toàn bộ vòng đời gói đăng ký, không chỉ lần mua đầu tiên. Các lần gia hạn và chuyển đổi dùng thử là sự kiện từ cửa hàng, không có phiên ứng dụng nào để SDK phía client của AppsFlyer ghi nhận. Adapty nhận các sự kiện gói đăng ký phía server và chuyển tiếp chúng đến AppsFlyer, nhờ đó số liệu chiến dịch tiếp tục được cập nhật lâu sau lần cài đặt ban đầu. Hoàn tiền cũng đi theo cách tương tự, và AppsFlyer sẽ khấu trừ chúng khỏi doanh thu chiến dịch.
• Tối ưu hóa chiến dịch quảng cáo với dữ liệu sự kiện gói đăng ký. AppsFlyer chuyển tiếp các sự kiện in-app từ Adapty đến các mạng quảng cáo của bạn dưới dạng postback. Các dịch vụ quản lý ngân sách quảng cáo của bạn có thể tối ưu hóa dựa trên những gì người dùng thực sự đã thanh toán.
• Lọc phân tích Adapty theo chiến dịch. Adapty lưu attribution của AppsFlyer trên từng hồ sơ người dùng, đến tận cấp ad set và creative, và biểu đồ gói đăng ký có thể lọc theo đó.
• Hiển thị paywall khác nhau theo từng chiến dịch. Phân khúc Adapty lọc theo cùng các trường attribution — chiến dịch, ad set và creative. Sử dụng phân khúc làm đối tượng để khớp paywall với quảng cáo đã thu hút người dùng.

Cách tích hợp hoạt động

Adapty nhận dữ liệu attribution từ AppsFlyer và gửi các sự kiện gói đăng ký ngược lại cho AppsFlyer. Cả hai đều phụ thuộc vào một giá trị duy nhất: AppsFlyer ID — một chuỗi do AppsFlyer tạo ra khi ứng dụng của bạn khởi chạy lần đầu tiên.

1. Khi người dùng cài đặt ứng dụng của bạn, AppsFlyer SDK sẽ gán cho họ một ID duy nhất.
2. Ứng dụng của bạn truyền ID đó cho Adapty, và Adapty lưu nó vào hồ sơ người dùng dưới tên appsflyer_id.
3. Ứng dụng của bạn cũng truyền dữ liệu attribution của AppsFlyer cho Adapty, và Adapty lưu dữ liệu đó vào cùng hồ sơ người dùng.
4. Sau đó, khi người dùng kích hoạt một sự kiện gói đăng ký — ví dụ: bắt đầu dùng thử hoặc mua sản phẩm, máy chủ của Adapty sẽ gửi sự kiện đó đến S2S API của AppsFlyer với cùng appsflyer_id.
5. AppsFlyer khớp ID đó với lượt cài đặt đã được attribution trước đó, nhờ vậy lượt mua hàng sẽ kế thừa thông tin chiến dịch và nguồn media của lượt cài đặt đó.

Hướng dẫn cài đặt

Trước khi bắt đầu:

• Xác nhận rằng gói AppsFlyer của bạn hỗ trợ S2S in-app events. Gói Zero cơ bản của AppsFlyer không hỗ trợ: API của gói này sẽ từ chối mọi event Adapty gửi với lỗi 403 Forbidden.
• Tích hợp AppsFlyer SDK vào ứng dụng của bạn. AppsFlyer ID mà tích hợp này phụ thuộc vào chỉ tồn tại sau khi SDK đó khởi tạo. Một tích hợp server-side đơn thuần sẽ không tạo ra ID này.
• Tắt tất cả các tích hợp attribution khác. Adapty chỉ chấp nhận một nguồn attribution cho mỗi hồ sơ người dùng và không thể ghi đè giá trị đã có. Trên iOS, attribution Apple Ads không tự nhiên (non-organic) luôn được ưu tiên — xem Chọn một nguồn attribution duy nhất.

Tạo S2S token trong AppsFlyer

Adapty xác thực với API S2S của AppsFlyer bằng token do bạn tạo. Chỉ admin của AppsFlyer mới có thể mở trang Tokens, vì vậy hãy nhờ admin tạo token nếu tài khoản của bạn không phải admin. Bỏ qua đến Cấu hình Adapty nếu bạn đã có token.

1. Đăng nhập vào AppsFlyer.

2. Nhấp vào tên tài khoản ở góc trên bên phải và mở Security center.

   

3. Trên trang Manage your account security, tìm thẻ AppsFlyer API and S2S tokens và nhấp vào Manage your AppsFlyer tokens. Trang Tokens sẽ mở ra.

4. Nhấp vào New token.

   

5. Nhập Name cho token. Tên này chỉ để bạn tham khảo và có thể thay đổi sau.

6. Chọn loại token S2S. Bất kỳ loại nào khác sẽ làm hỏng tích hợp.

7. Nhấp vào Create new token.

8. Tìm token mới của bạn trong danh sách. AppsFlyer che giấu giá trị token, vì vậy hãy nhấp vào biểu tượng sao chép trong cột Token để lấy giá trị đó.

   

Cấu hình Adapty

1. Mở Integrations > AppsFlyer trong Adapty Dashboard.
2. Bật toggle AppsFlyer.
3. Nếu bạn đã kết nối ứng dụng với App Store, trường iOS App ID sẽ tự động được điền bằng Apple ID số của ứng dụng. Nếu trường này trống, hãy kết nối tài khoản App Store trước. Android không có trường tương đương.
4. Dán S2S token vào trường Production của S2S key for iOS, S2S key for Android, hoặc cả hai.
5. Điền vào các trường Sandbox để tách dữ liệu mua thử nghiệm khỏi số liệu production — xem Tách dữ liệu sandbox khỏi production.

6. Trong phần How the revenue data should be send, chọn loại doanh thu mà Adapty gửi dưới dạng af_revenue. Ba tùy chọn tương ứng với các chế độ xem doanh thu trong Adapty Analytics, vì vậy lựa chọn của bạn cũng xác định chế độ xem mà con số AppsFlyer của bạn cần khớp với.

7. Thiết lập các tùy chọn còn lại:

8. Đổi tên hoặc vô hiệu hóa từng sự kiện trong phần Events names — xem Tên sự kiện.

   

9. Nhấn Save.

Giữ dữ liệu sandbox tách khỏi môi trường production

Để các giao dịch thử nghiệm không ảnh hưởng đến số liệu thực, hãy gửi chúng đến một ứng dụng AppsFlyer riêng biệt. Đăng ký một ứng dụng thứ hai cho các bản build phát triển, sau đó dán token của ứng dụng đó vào trường Sandbox trong phần cài đặt của từng nền tảng.

Adapty phân loại mọi giao dịch theo môi trường — giao dịch thực gửi đến ứng dụng có token trong Production, giao dịch thử nghiệm gửi đến ứng dụng trong Sandbox. Nếu bạn muốn báo cáo tất cả trong một ứng dụng, hãy dán cùng một token vào cả hai trường.

Các giao dịch mua hàng trong quá trình App Store review và TestFlight đều là giao dịch sandbox, dù chúng chạy trên bản build production. Adapty gửi các giao dịch này với key Sandbox.

Cấu hình code ứng dụng của bạn

1. Đăng ký callback chuyển đổi với AppsFlyer SDK. Trên iOS, implement protocol AppsFlyerLibDelegate; trên Android, interface AppsFlyerConversionListener; trên Unity, interface IAppsFlyerConversionData. Trên React Native và Flutter, truyền một handler vào phương thức onInstallConversionData.
2. Chờ AppsFlyer gọi callback đó. AppsFlyer thực hiện attribution cho từng lượt cài đặt trên server của mình, nên kết quả sẽ đến app của bạn theo cách bất đồng bộ thay vì ngay lúc khởi chạy. SDK sẽ gọi lại callback này trong mỗi phiên tiếp theo.
3. Bên trong callback, đọc AppsFlyer ID của người dùng bằng getAppsFlyerUID và truyền nó cho Adapty thông qua setIntegrationIdentifier(). Các sự kiện của Adapty chỉ đến đúng người dùng AppsFlyer khi có giá trị này.
4. Bên trong cùng callback đó, truyền dữ liệu attribution của AppsFlyer cho Adapty bằng updateAttribution(). Điều này cho Adapty biết chiến dịch nào đã tạo ra lượt cài đặt. Trên iOS và Android SDK 4.1 trở lên, phương thức được đổi tên thành updateExternalAttribution().
5. Dùng await Adapty.identify() thay vì chạy song song với bước 3 và 4. Adapty tạo một hồ sơ người dùng ẩn danh lúc kích hoạt, sau đó chuyển sang hồ sơ đã xác định khi identify() hoàn tất. Một appsflyer_id được đặt trong khoảng thời gian chuyển đổi đó không phải lúc nào cũng được giữ lại.

Để xem toàn bộ trình tự, hãy xem thứ tự gọi trong SDK iOS, Android, React Native, Flutter, Unity, Capacitor, và Kotlin Multiplatform.

class YourAppsFlyerLibDelegateImplementation {
    // Find your implementation of AppsFlyerLibDelegate
    // and update onConversionDataSuccess method:
    func onConversionDataSuccess(_ conversionInfo: [AnyHashable : Any]) {
        let uid = AppsFlyerLib.shared().getAppsFlyerUID()
        Adapty.setIntegrationIdentifier(.appsflyerId(uid))
        Adapty.updateExternalAttribution(conversionInfo, provider: .appsflyer)
    }
}

val conversionListener: AppsFlyerConversionListener = object : AppsFlyerConversionListener {
    override fun onConversionDataSuccess(conversionData: Map<String, Any>) {
        val uid = AppsFlyerLib.getInstance().getAppsFlyerUID(context)
        Adapty.setIntegrationIdentifier(AdaptyIntegrationIdentifier.appsflyerId(uid)) { error ->
            if (error != null) {
                // handle the error
            }
        }
        Adapty.updateExternalAttribution(conversionData, AdaptyExternalAttributionProvider.APPSFLYER) { error ->
            if (error != null) {
                //handle the error
            }
        }
    }
}

appsFlyer.onInstallConversionData(installData => {
    appsFlyer.getAppsFlyerUID(async (error, appsFlyerUID) => {
        if (error) {
            // handle the error
            return;
        }
        try {
            await adapty.setIntegrationIdentifier('appsflyer_id', appsFlyerUID);
            await adapty.updateAttribution(installData, 'appsflyer');
        } catch (error) {
            // handle `AdaptyError`
        }
    });
});

// ...
appsFlyer.initSdk(/*...*/);

AppsflyerSdk appsflyerSdk = AppsflyerSdk(<YOUR_OPTIONS>);

appsflyerSdk.onInstallConversionData((data) async {
    try {
        final appsFlyerUID = await appsFlyerSdk.getAppsFlyerUID();

        await Adapty().setIntegrationIdentifier(
          key: "appsflyer_id",
          value: appsFlyerUID,
        );

        await Adapty().updateAttribution(data, source: "appsflyer");
    } on AdaptyError catch (adaptyError) {
        // handle the error
    } catch (e) {
        // handle the error
    }
});

appsflyerSdk.initSdk(
    registerConversionDataCallback: true,
    registerOnAppOpenAttributionCallback: true,
    registerOnDeepLinkingCallback: true,
);

using AdaptySDK;
using AppsFlyerSDK;

// before SDK initialization
AppsFlyer.getConversionData(this.name);

// in your IAppsFlyerConversionData
void onConversionDataSuccess(string conversionData) {
    string appsFlyerId = AppsFlyer.getAppsFlyerId();

    Adapty.SetIntegrationIdentifier(
      "appsflyer_id",
      appsFlyerId,
      (error) => {
        // handle the error
    });

    Adapty.UpdateExternalAttribution(
      conversionData,
      "appsflyer",
      (error) => {
        // handle the error
    });
}

Xác minh tích hợp

1. Kích hoạt một giao dịch mua sandbox và mở Event Feed của ứng dụng. Mọi lần gửi đều hiển thị ở đó. Để xem phản hồi của AppsFlyer khi có lần gửi thất bại, hãy di chuột qua hàng tương ứng.
2. Trong AppsFlyer, mở Settings > SDK Integration Tests > Live Events và chọn thiết bị thử nghiệm của bạn. Live Events liệt kê các sự kiện S2S khi chúng đến, trước khi chúng xuất hiện trên dashboard Activity của AppsFlyer.
3. Mở dashboard Activity của ứng dụng và xác nhận sự kiện, doanh thu cũng như media source. Hãy đợi khoảng một giờ — sự kiện S2S không hiển thị ngay trên dashboard này.

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

Adapty gửi một POST request cho mỗi sự kiện tới https://api3.appsflyer.com/inappevent/{app_id}, với S2S token trong header authentication. API 2 sử dụng https://api2.appsflyer.com/inappevent/{app_id}.

{
  "appsflyer_id": "1699887556000-6192770",
  "eventName": "af_subscribe",
  "eventTime": "2026-03-01 12:00:00",
  "eventValue": "{\"af_content_id\":\"yearly.premium.6999\",\"af_order_id\":\"GPA.3383-4699-1373-07113\",\"store_country\":\"US\",\"profile_country\":\"US\",\"af_content_type\":\"in_app\",\"af_revenue\":\"9.9900\",\"af_currency\":\"USD\",\"af_quantity\":\"1\"}",
  "os": "17.0.1",
  "bundleIdentifier": "com.example.app",
  "customer_user_id": "user_12345",
  "eventCurrency": "USD",
  "ip": "192.168.100.1",
  "advertising_id": "00000000-0000-0000-0000-000000000000",
  "idfa": "00000000-0000-0000-0000-000000000000",
  "idfv": "00000000-0000-0000-0000-000000000000",
  "att": "3"
}

eventValue mang theo thông tin về giao dịch mua. Bốn tham số cuối chỉ xuất hiện trong các sự kiện có doanh thu:

Tên sự kiện

Theo mặc định, Adapty ánh xạ các sự kiện có doanh thu sang tên sự kiện chuẩn của AppsFlyer thay vì gửi tên riêng của mình dưới dạng sự kiện tùy chỉnh. Điều này quan trọng khi bạn chuyển tiếp sự kiện đến các mạng quảng cáo: mạng sẽ xử lý các tên chuẩn mà nó đã nhận biết, giúp bạn không phải tự tạo mapping cho từng sự kiện.

Các sự kiện Adapty khác giữ nguyên tên của chúng, ví dụ subscription_refunded. Trong phần Events names của trang tích hợp AppsFlyer, bạn có thể đổi tên bất kỳ sự kiện nào hoặc tắt những sự kiện không cần thiết. Để xem danh sách đầy đủ những gì Adapty có thể gửi, hãy xem Sự kiện.

Hạn chế

• Hồ sơ người dùng không có appsflyer_id sẽ không tạo ra sự kiện nào. AppsFlyer khớp một sự kiện với lượt cài đặt đã tạo ra ID đó, và đọc thông tin chiến dịch từ lượt cài đặt đó. Adapty sẽ không gửi gì nếu không có ID này, và Event Feed sẽ đánh dấu các hồ sơ người dùng này — xem Sự kiện không đến được AppsFlyer.
• Không có dữ liệu lịch sử. Adapty chỉ chuyển tiếp các sự kiện kể từ thời điểm bạn bật tích hợp. Các giao dịch mua trong quá khứ sẽ không bao giờ đến AppsFlyer.
• Thông tin thiết bị vẫn trống trong dữ liệu thô của AppsFlyer. Một sự kiện S2S chỉ mang theo những gì có trong request. Device Model, Device Category, Language, Operator, WIFI, App Version và App Name không có tham số S2S tương ứng, vì vậy không có dữ liệu nào được gửi theo cách này có thể điền vào các trường đó.

Khắc phục sự cố

• Sự kiện không đến được AppsFlyer
• Giao dịch mua hiển thị là organic
• Sự kiện cũ xuất hiện với ngày hôm nay
• Renewals rơi vào sai ngày
• Doanh thu trong AppsFlyer không khớp với Adapty Analytics
• Failed to authenticate trong Event Feed
• access_level_updated hiển thị là thất bại trong Event Feed

Sự kiện không đến được AppsFlyer

Trước tiên hãy mở Event Feed. Lỗi giao nhận thất bại sẽ hiển thị lỗi mà AppsFlyer trả về. Sau đây là những nguyên nhân phổ biến nhất:

• Hồ sơ người dùng không có appsflyer_id. Hãy kiểm tra xem app của bạn có gọi getAppsFlyerUID và truyền kết quả vào setIntegrationIdentifier trên mọi nền tảng bạn hỗ trợ không — xem Cấu hình mã ứng dụng.
• Thiếu App ID cho nền tảng đó. AppsFlyer nhận diện mỗi app qua ID, vì vậy Adapty sẽ không gửi gì nếu thiếu thông tin này. Sự kiện iOS cần iOS App ID trên trang tích hợp; sự kiện Android cần package name từ App settings > Android SDK — xem Cấu hình Adapty.
• Giao dịch là sandbox nhưng Sandbox key chưa được điền. Xem Giữ dữ liệu sandbox khỏi môi trường production.
• Sự kiện đã bị tắt trong phần Events names.

Một lần gửi thành công không đảm bảo AppsFlyer lưu giữ sự kiện đó. AppsFlyer trả về 200 OK cho bất kỳ yêu cầu nào có định dạng hợp lệ, sau đó loại bỏ các sự kiện có appsflyer_id không khớp với bất kỳ lượt cài đặt thực nào.

Giao dịch mua hiển thị dưới dạng organic

Mỗi appsflyer_id xác định một lượt cài đặt, và mọi sự kiện mang ID đó đều kế thừa attribution của lượt cài đặt đó — chiến dịch tạo ra nó, hoặc không có gì nếu lượt cài đặt là organic. AppsFlyer cần 20–30 giây hoặc hơn để gán attribution cho một lượt cài đặt mới. Một sự kiện đến trước thời điểm đó sẽ không có attribution để kế thừa, vì vậy AppsFlyer đánh dấu nó là organic không được gán attribution.

Để tránh điều này, hãy trì hoãn việc hiển thị paywall đủ lâu để AppsFlyer hoàn tất xử lý lượt cài đặt.

Nếu mọi sự kiện đều hiển thị là organic, không chỉ riêng lượt mua đầu tiên sau khi khởi chạy, thì nguyên nhân là do attribution chứ không phải thời điểm: một nguồn khác đã nhận hồ sơ người dùng trước. Xem Chọn một nguồn attribution duy nhất.

Sự kiện cũ xuất hiện với ngày hôm nay

Sự kiện có thể đến Adapty muộn vì hai lý do:

• Khi App Store Server Notifications hiển thị Delayed trong App Store Connect, Apple sẽ xếp hàng các thông báo của mình. Một lần gia hạn sau đó sẽ đến Adapty rất lâu sau khi nó xảy ra — xem App Store Server Notifications hiển thị “Delayed”.
• Các sự kiện có ngày hồi tố sẽ được chuyển qua bất cứ khi nào Exclude historical events đang tắt.

AppsFlyer sẽ không chấp nhận các timestamp cũ như vậy. Để đảm bảo xử lý sự kiện nhất quán, Adapty thay thế eventTime bằng thời gian hiện tại cho bất kỳ sự kiện nào cũ hơn 26 giờ. Bạn không thể tắt tính năng ghi đè này.

Các lần gia hạn rơi vào sai ngày

Apple thông báo cho Adapty về các lần gia hạn và chuyển đổi dùng thử trước khi chúng xảy ra, và Adapty chuyển tiếp chúng ngay lập tức với eventTime trong tương lai không thay đổi. AppsFlyer chỉ giữ nguyên timestamp trong tương lai khi nó rơi vào ngày nhận — một lần gia hạn được đặt ngày mai sẽ bị gán theo thời gian nhận hôm nay thay thế.

Bật Delay events with a future datetime trong cài đặt tích hợp. Adapty sẽ giữ lại từng sự kiện cho đến khi đến thời điểm đó, để AppsFlyer ghi lại đúng ngày Apple công bố. Xem Dấu thời gian sự kiện với ngày trong tương lai.

Doanh thu trong AppsFlyer không khớp với Adapty Analytics

Adapty và AppsFlyer tính cùng một giao dịch mua theo cách khác nhau. Những khác biệt này gần như là nguyên nhân của mọi sự không khớp.

• Dashboard Overview của AppsFlyer nhóm doanh thu theo ngày cài đặt; biểu đồ của Adapty nhóm theo ngày sự kiện. Trong AppsFlyer, một lần gia hạn tháng 7 từ lượt cài đặt tháng 1 sẽ được tính vào tháng 1. Hãy so sánh dashboard đó với phân tích cohort của Adapty, vốn cũng nhóm doanh thu theo tháng cài đặt. Báo cáo dữ liệu thô của AppsFlyer nhóm theo ngày sự kiện, vì vậy hãy so sánh những báo cáo đó với biểu đồ của Adapty.
• Các giao dịch mua từ hồ sơ người dùng không có appsflyer_id sẽ không bao giờ đến được AppsFlyer. Chúng chỉ lưu trong Adapty Analytics. Xem Sự kiện không đến được AppsFlyer.
• AppsFlyer chỉ hiển thị con số doanh thu bạn đã chọn trong Adapty. Cài đặt How the revenue data should be send quyết định Adapty gửi doanh thu gộp, doanh thu sau phí, hay doanh thu ròng. Việc so sánh số liệu đó với một chế độ xem khác trong Adapty Analytics sẽ tạo ra khoảng chênh lệch bằng đúng phần hoa hồng, thuế, hoặc cả hai.
• Adapty dùng múi giờ báo cáo của ứng dụng; AppsFlyer nhận UTC. Các tích hợp luôn nhận timestamp theo UTC, bất kể bạn đặt gì trong App Settings. Một giao dịch mua lúc 23:30 UTC ngày 1/7 sẽ rơi vào ngày 2/7 trong Adapty nếu múi giờ báo cáo của bạn là +02:00.
• AppsFlyer thiếu các sự kiện lịch sử. Có hai nguyên nhân có thể xảy ra. Khi bật Exclude historical events, lịch sử AppsFlyer của người dùng bắt đầu từ lần đầu tiên họ khởi chạy bản build có tích hợp Adapty. Ngoài ra, Adapty cũng không bao giờ bổ sung ngược các sự kiện đã xử lý trước khi bạn bật tích hợp.
• Các giao dịch mua sandbox sẽ đến ứng dụng AppsFlyer được chỉ định bởi Sandbox key. Nếu đó là ứng dụng production, các giao dịch thử nghiệm sẽ làm tăng doanh thu của ứng dụng đó. Xem Giữ dữ liệu sandbox tách khỏi production.
• Các sự kiện bị tắt trong tích hợp sẽ không bao giờ đến được AppsFlyer. Adapty Analytics vẫn đếm chúng. Hãy kiểm tra phần Events names — việc tắt subscription_renewed sẽ loại bỏ phần lớn doanh thu của bất kỳ ứng dụng đã vận hành lâu dài nào.

Failed to authenticate trong Event Feed

AppsFlyer từ chối thông tin xác thực khi chúng không khớp với phiên bản API. API 2 yêu cầu Dev key; API 3 yêu cầu S2S token. Chuyển đổi phiên bản mà không thay thế key sẽ tạo ra lỗi này cho mỗi sự kiện.

Tạo token mới trong AppsFlyer Security Center và dán vào các trường S2S key, hoặc làm theo hướng dẫn Switch from AppsFlyer S2S API 2 to 3.

access_level_updated hiển thị là thất bại trong Event Feed

access_level_updated là một sự kiện chỉ dành cho webhook. Adapty không bao giờ gửi sự kiện này đến tích hợp này. Tuy nhiên, Adapty ghi lại kết quả cho mọi tích hợp đã bật, và một sự kiện không được hỗ trợ sẽ được hiển thị là thất bại.