Cấu hình tích hợp App Store

Để kết nối ứng dụng iOS của bạn với Adapty, hãy nhập thông tin xác thực App Store vào App settings > iOS SDK. Sau đó Adapty sẽ:

  • Xác thực các giao dịch mua.
  • Nhận các sự kiện gói đăng ký.
  • Đồng bộ sản phẩm của bạn với App Store Connect.

Nếu các sự kiện mua hàng hoặc gói đăng ký ngừng được ghi nhận trong Adapty, hãy kiểm tra từng thông tin xác thực.

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

  • Bạn cần quyền truy cập vào ứng dụng trong App Store Connect. Nếu ứng dụng chưa có ở đó, hãy thiết lập App Store Connect. Nếu bạn chưa có quyền truy cập vào nền tảng, hãy yêu cầu cấp quyền.
  • Nhóm của bạn cần quyền truy cập vào App Store Connect API — đây là điều kiện cần thiết để tạo khóa truy cập. Nếu nhóm bạn chưa có, hãy nhờ Account Holder gửi yêu cầu. Apple sẽ xem xét từng yêu cầu.
  • Mở hai tab trình duyệt: một tab mở ứng dụng của bạn trong App Store Connect, tab còn lại mở App settings > iOS SDK trong Adapty. Bạn sẽ sao chép các giá trị qua lại giữa hai tab trong suốt hướng dẫn này.

Tổng quan

Mọi thông tin xác thực trong hướng dẫn này đều bắt buộc. Adapty sử dụng từng thông tin cho một phần khác nhau trong quá trình trao đổi dữ liệu với App Store. Để hoàn tất thiết lập, hãy thực hiện bảy bước sau:

  1. Nhập Bundle ID và Apple App ID
  2. Nhập app-specific shared secret
  3. Bật App Store server notifications với URL từ Adapty
  4. Thêm In-App Purchase key
  5. Thêm App Store Connect API key
  6. Cài đặt SDK Adapty và thực hiện giao dịch mua sandbox
  7. Xác minh tất cả thông tin xác thực

Nhập Bundle ID và Apple App ID

Hai giá trị dùng để xác định ứng dụng của bạn trong App Store Connect: Bundle ID và Apple ID (được gọi là Apple App ID trong Adapty). Adapty cần Bundle ID để xử lý các giao dịch mua. Với Apple ID, Adapty có thể:

  • Tìm các sản phẩm của bạn trong App Store Connect và tạo sản phẩm mới ở đó.
  • Hiển thị trạng thái App Store và giá của các sản phẩm.
  • Gửi tin nhắn thời gian thực cho Retention Messaging.
  • Xác định ứng dụng của bạn với các tích hợp attribution, chẳng hạn như AppsFlyer.

Apple gán Apple ID khi bạn thêm ứng dụng vào App Store Connect, vì vậy hãy nhập ID này ngay cả trước khi ứng dụng của bạn được đăng lên App Store.

  1. Open App Store Connect. Select your app and proceed to General > App Information section.

  2. Copy the Bundle ID in the General Information sub-section.

    Copy only the identifier — reverse-DNS format with no spaces, for example, com.company.app. App Store Connect shows the app name next to it in other views, like the apps list; pasting that instead of the identifier makes the connection between Adapty and the App Store fail to validate.

asc-app-information-bundle-id.webp
  1. Open the App settings > iOS SDK tab from the Adapty top menu and paste the copied value to the Bundle ID field.
app-settings-bundle-id.webp
  1. Get back to the App information page in App Store Connect and copy Apple ID from there.
asc-app-information-apple-id.webp
  1. On the App settings > iOS SDK page in the Adapty dashboard, paste the ID to the Apple App ID field.
app-settings-apple-app-id.webp

Nhập app-specific shared secret

Adapty cần app-specific shared secret để xác thực purchase receipt và tạo sản phẩm trong App Store Connect.

  1. Trong App Store Connect, mở trang App Information của ứng dụng. Trong phần App-Specific Shared Secret, nhấp vào Manage.

    App-Specific Shared Secret section on the App Information page in App Store Connect
  2. Sao chép secret. Nếu ứng dụng chưa có secret, hãy nhấp Generate trước. Để tạo secret, bạn cần có vai trò Account Holder hoặc Admin trong App Store Connect. Nếu không có vai trò nào trong số đó, hãy nhờ người có vai trò đó tạo secret và gửi cho bạn.

    Trừ khi bạn nhận ứng dụng qua chuyển giao ứng dụng, đừng nhấp Regenerate: secret hiện tại sẽ ngừng hoạt động ở mọi nơi đang sử dụng nó.

    App-Specific Shared Secret window with the secret
  3. Trong Adapty, dán secret vào trường App Store Connect shared secret.

    App Store Connect shared secret field in Adapty
  4. Nhấp Save.

Bật thông báo server của App Store bằng URL từ Adapty

Apple gửi thông báo server đến Adapty về các lần gia hạn, hoàn tiền và các sự kiện gói đăng ký khác ngay khi chúng xảy ra. Adapty ghi lại những sự kiện này ngay cả khi ứng dụng của bạn không báo cáo giao dịch nào.

Nếu Apple đã gửi các thông báo này đến một máy chủ, hãy thiết lập chuyển tiếp đến máy chủ đó trước khi bạn thay thế URL của nó trong App Store Connect. Trong Adapty, nhập URL của máy chủ đó vào trường URL for forwarding raw Apple events và nhấn Save. Adapty sẽ chuyển tiếp các thông báo nhận được từ Apple đến máy chủ đó.

Nếu backend của bạn cần giữ nguyên URL trong App Store Connect, hãy chuyển các thông báo đến Adapty từ backend của bạn thay thế.

  1. Trong Adapty, mở ứng dụng bạn đang kết nối: mỗi ứng dụng Adapty có URL thông báo riêng. Đi đến App settings > iOS SDK. Trong mục App Store server notifications, sao chép URL từ trường URL for App Store server notifications.

    URL for App Store server notifications in the App Store server notifications section in Adapty
  2. Trong App Store Connect, mở trang App Information của ứng dụng.

  3. Trong mục App Store Server Notifications, tìm Production Server URL. Nếu đã có URL ở đó, nhấn Edit. Nếu chưa có, nhấn Set Up URL.

    App Store Server Notifications section on the App Information page in App Store Connect
  4. Dán URL từ Adapty vào và nhấn Save.

    Production Server URL dialog in App Store Connect with the URL from Adapty
  5. Để nhận thông báo từ các bài kiểm thử sandbox của bạn trong Adapty, lặp lại bước 3 và 4 cho Sandbox Server URL.

Thêm khóa In-App Purchase

Adapty sử dụng khóa In-App Purchase để xác thực các giao dịch mua và ký các ưu đãi. Nếu bạn chưa có file khóa, hãy tạo khóa trong App Store Connect trước. Để thêm khóa vào Adapty:

  1. Để tìm Issuer ID và Key ID của khóa, trong App Store Connect, truy cập Users and Access > Integrations > In-App Purchase. Nếu người khác đã tạo khóa và gửi cho bạn Issuer ID, Key ID và file, hãy bỏ qua bước này.

    Issuer ID và Key ID của khóa In-App Purchase trong App Store Connect
  2. Trong Adapty, truy cập App settings > iOS SDK. Trong phần In-app purchase API (StoreKit 2), điền vào các trường:

    • Issuer ID: Sao chép từ trang In-App Purchase trong App Store Connect.
    • Key ID: Sao chép từ danh sách Active trên trang In-App Purchase, bên cạnh khóa bạn đã tải xuống.
    • Private key (.p8 file): Tải lên file bạn đã tải xuống.
    Các trường Issuer ID, Key ID và Private key (.p8 file) trong phần In-app purchase API (StoreKit 2) trong Adapty
  3. Adapty ký ưu đãi bằng khóa In-App Purchase. Trong phần App Store promotional offers, nhập lại khóa:

    • Subscription key ID: Key ID từ bước 2.
    • Subscription key (.p8 file): File từ bước 2.
    Các trường Subscription key ID và Subscription key (.p8 file) trong phần App Store promotional offers

    Nếu dùng khóa khác, hệ thống sẽ lưu mà không báo lỗi, nhưng người dùng sẽ không nhận được ưu đãi.

  4. Nhấp Save. Adapty xác minh khóa trong phần In-app purchase API (StoreKit 2) với Apple trước khi lưu trang. Nếu Apple từ chối khóa, trang sẽ hiển thị “The provided field values are incorrect”: xem lại các giá trị.

Thêm App Store Connect API key

Adapty sử dụng App Store Connect API key để tạo sản phẩm trong App Store Connect và đồng bộ trạng thái cũng như giá của chúng. Đây là key khác với In-App Purchase key, mặc dù cả hai đều dùng chung tên trường Issuer ID và Key ID.

Adapty cần một team key với quyền truy cập Admin. Nếu bạn chưa có, hãy tạo key trong App Store Connect trước. Để kết nối key trong Adapty:

  1. Để tìm Issuer ID và Key ID của team key, trong App Store Connect, hãy vào Users and Access > Integrations > App Store Connect API và mở tab Team Keys. Nếu người khác đã tạo key và gửi cho bạn Issuer ID, Key ID và file, hãy bỏ qua bước này.

    Issuer ID và Key ID của một team key trên tab Team Keys trong App Store Connect
  2. Trong Adapty, vào App settings > iOS SDK. Trong phần App Store Connect API key, nhấp vào Connect API Key.

    Phần App Store Connect API key trong Adapty, với nút Connect API Key
  3. Điền vào các trường:

    • Issuer ID: Sao chép từ tab Team Keys trong App Store Connect.
    • Key ID: Sao chép từ danh sách Active trên tab Team Keys, bên cạnh key bạn đã tải xuống.
    • Private key (.p8 file): Tải lên file bạn đã tải xuống cho team key.
    Các trường Issuer ID, Key ID và Private key (.p8 file) trong cửa sổ App Store Connect API key
  4. Bạn có thể thay thế key đã kết nối sau này, nhưng không thể xóa nó. Hãy đảm bảo key thuộc về team App Store Connect sở hữu ứng dụng này, rồi nhấp vào Connect. Từ đó trở đi, bạn sẽ chọn từng App Store Product ID từ các sản phẩm của mình trong App Store Connect thay vì nhập thủ công.

    Adapty không xác minh key với Apple khi bạn kết nối. Một key sai sẽ thất bại mà không có thông báo gì về key đó: các sản phẩm sẽ không hiển thị trạng thái App Store và dropdown App Store Product ID sẽ trống. Để sửa key sai, hãy thay thế nó.

Kiểm tra từng thông tin xác thực

Để xác nhận rằng Adapty xác thực giao dịch mua, hãy cài đặt SDK vào ứng dụng của bạn và thực hiện giao dịch mua trong sandbox.

Giao dịch mua trong sandbox chỉ sử dụng một số thông tin xác thực. Hãy kiểm tra từng thông tin sau khi mua, và kiểm tra lại bất cứ khi nào giao dịch mua hoặc sự kiện gói đăng ký ngừng được gửi đến Adapty:

  • Bundle ID, Apple App ID, và App Store Connect shared secret: So sánh ba giá trị này với Bundle ID, Apple ID, và secret trong mục App-Specific Shared Secret trên trang App Information trong App Store Connect.
  • App Store server notifications: Trạng thái trong phần này hiển thị Active khi Adapty nhận được thông báo về một giao dịch mua hoặc gia hạn. Nếu hiển thị trạng thái khác, hãy kiểm tra URL server.
  • In-app purchase API (StoreKit 2): Adapty xác minh key với Apple khi bạn lưu. Nếu sau này các giao dịch mua trong ứng dụng không mở khóa được quyền truy cập, key có thể đã ngừng hoạt động: hãy thay thế key.
  • App Store promotional offers: Đảm bảo Subscription key ID khớp với Key ID trong phần In-app purchase API (StoreKit 2). Nếu chúng khác nhau, hãy nhập cùng một key vào cả hai phần.
  • App Store Connect API key: Mỗi sản phẩm App Store hiển thị trạng thái trong cột App Store status trên trang Products. Nếu một sản phẩm hiển thị dấu gạch ngang hoặc Not Connected, hãy kiểm tra key và Apple App ID.

Ngay sau khi thiết lập, Analytics có thể ghi nhận số lượng dùng thử và mua hàng nhiều hơn số lượt cài đặt, và nhiều hơn những gì Event Feed hiển thị. Sự chênh lệch này đến từ các giao dịch không có hồ sơ người dùng: các giao dịch mua của người dùng chưa mở phiên bản ứng dụng có tích hợp Adapty SDK.

Những chênh lệch khác giữa Adapty và báo cáo từ cửa hàng xuất phát từ cách mỗi bên tính số lượt mua, không phải từ thông tin xác thực.

Các bước tiếp theo

Để chuẩn bị ứng dụng cho việc phát hành, hãy xem qua danh sách kiểm tra trước khi phát hành.

Nếu ứng dụng của bạn cũng có trên Google Play, hãy kết nối cửa hàng đó.