Kiểm soát thông báo cửa hàng trong Capacitor SDK

App Store và Google Play đôi khi cần hiển thị thông báo cho người dùng của bạn về gói đăng ký của họ:

  • App Store: Yêu cầu chấp thuận tăng giá, thông báo sự cố thanh toán, hoặc ưu đãi thu hút khách hàng cũ. Theo mặc định, StoreKit tự hiển thị các thông báo này khi ứng dụng đang mở.
  • Google Play: Thông báo rằng thanh toán gói đăng ký bị từ chối và cần cập nhật phương thức thanh toán. Từ SDK 4.3.0 trở đi, Adapty SDK mặc định yêu cầu các thông báo này mỗi khi một Activity của ứng dụng khởi động sau activate, kể cả khi ứng dụng quay lại foreground.

Dù thế nào, thông báo vẫn có thể xuất hiện trên flow, onboarding hoặc màn hình thanh toán. Để tự chọn thời điểm hiển thị, hãy chuyển SDK sang chế độ xử lý thông báo thủ công và gọi showStoreMessages khi thông báo không làm gián đoạn người dùng.

Warning

Ở chế độ thủ công, cửa hàng sẽ không tự hiển thị thông báo. Nếu ứng dụng của bạn không bao giờ gọi showStoreMessages, người dùng sẽ không bao giờ nhìn thấy yêu cầu xác nhận tăng giá, thông báo vấn đề thanh toán hay thông báo thanh toán bị từ chối.

Trước khi bắt đầu

Bạn cần:

  • Adapty Capacitor SDK 4.3.0 trở lên: Các phiên bản cũ hơn không có API thông báo từ cửa hàng.
  • iOS 16 trở lên để nhận thông báo từ App Store: StoreKit không gửi thông báo đến ứng dụng trên các phiên bản cũ hơn. Trên iOS 15, getPendingStoreMessageTypes và showStoreMessages sẽ trả về lỗi decodingFailed, vì vậy nếu ứng dụng của bạn hỗ trợ iOS 15, hãy bắt lỗi này như trong các ví dụ bên dưới.

Bật xử lý thủ công

Để chỉ hiển thị thông báo từ cửa hàng khi ứng dụng của bạn gọi showStoreMessages, hãy đặt storeMessagesHandling thành 'manual' khi bạn kích hoạt SDK:


await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    storeMessagesHandling: 'manual', // 'auto' is the default
  },
});

Trên iOS, SDK sẽ thêm từng thông báo App Store vào danh sách chờ của phiên ứng dụng hiện tại. Trên Android, SDK ngừng tự yêu cầu thông báo Google Play. Với giá trị mặc định là 'auto', SDK không chặn thông báo App Store, do đó trên iOS, getPendingStoreMessageTypes và showStoreMessages sẽ không có gì để trả về hoặc hiển thị.

Lấy các loại tin nhắn đang chờ

Trên iOS, để kiểm tra xem có tin nhắn nào từ App Store đang chờ hay không, hãy gọi getPendingStoreMessageTypes. Hàm này trả về các loại tin nhắn đang chờ mà không hiển thị hay xóa chúng:

try {
  const pendingTypes = await adapty.getPendingStoreMessageTypes();

  if (pendingTypes === null) {
    // Android: Google Play decides whether a message applies when you show it
    await adapty.showStoreMessages();
  } else if (pendingTypes.includes('billing_issue')) {
    // For example, skip the upsell and show the billing message first
  }
} catch (error) {
  // On iOS 15, the call fails with decodingFailed (2006)
}

Trên Android, phương thức trả về null mà không gọi SDK native: Google Play không báo cáo các tin nhắn đang chờ, và chỉ quyết định xem tin nhắn có áp dụng hay không khi ứng dụng của bạn yêu cầu. Mảng rỗng có nghĩa là không có tin nhắn đang chờ trên iOS. Cho đến khi activate hoàn tất, mảng luôn rỗng.

Mỗi tin nhắn App Store có một trong các loại sau:

LoạiThông báo
genericThông báo chung từ App Store.
price_increase_consentYêu cầu đồng ý tăng giá gói đăng ký.
billing_issueThông báo về sự cố thanh toán gói đăng ký. Chỉ khả dụng trên iOS 16.4 trở lên.
win_back_offerƯu đãi thu hút khách hàng cũ đủ điều kiện. Chỉ khả dụng trên iOS 18 trở lên.

Các loại thông báo StoreKit mới sẽ có giá trị storekit_<number>. Hãy xử lý mọi giá trị ngoài bảng này như một loại mà SDK chưa nhận dạng được.

Hiển thị thông báo

Khi ứng dụng của bạn đến điểm mà thông báo cửa hàng sẽ không làm gián đoạn người dùng — ví dụ, sau khi người dùng đóng một flow hoặc hoàn tất onboarding — hãy gọi showStoreMessages:

try {
  await adapty.showStoreMessages();
} catch (error) {
  // handle the error
}
  • iOS: SDK hiển thị các tin nhắn đang chờ lần lượt từng cái một. Sau khi StoreKit hiển thị một tin nhắn, SDK xóa nó khỏi danh sách chờ. Nếu StoreKit không hiển thị được tin nhắn, SDK giữ lại tin nhắn đó cho lần gọi tiếp theo và tiếp tục xử lý các tin nhắn còn lại.
  • Android: SDK yêu cầu Google Play hiển thị tin nhắn cho Activity hiện tại. Google Play tự quyết định tin nhắn có áp dụng cho người dùng hay không, vì vậy một yêu cầu không phải lúc nào cũng hiển thị tin nhắn. Lệnh gọi trả về ngay lập tức mà không chờ Google Play và không báo cáo lỗi từ Google Play. Nếu người dùng sửa phương thức thanh toán từ tin nhắn, SDK sẽ đồng bộ các giao dịch mua của người dùng với Adapty, và profile listener của bạn sẽ nhận được mức độ truy cập đã cập nhật.

Hiển thị thông báo khi khởi động trên Android

Ở chế độ mặc định 'auto', Activity chứa ứng dụng của bạn khởi động trước khi activate chạy, do đó không kích hoạt yêu cầu và các thông báo Google Play sẽ không xuất hiện khi khởi động. Để hiển thị chúng khi khởi động, hãy gọi showStoreMessages một lần sau activate, chỉ trên Android:


await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY' });

if (Capacitor.getPlatform() === 'android') {
  await adapty.showStoreMessages();
}

Đừng thực hiện lệnh gọi này trên iOS: ở chế độ 'auto', nó không có gì để hiển thị, và trên iOS 15 thì nó sẽ bị lỗi.

Chỉ hiển thị một số loại thông báo nhất định

Để chỉ hiển thị một số thông báo App Store đang chờ xử lý, hãy truyền các loại vào ios.filter. Các thông báo còn lại vẫn ở trạng thái chờ:

await adapty.showStoreMessages({
  ios: { filter: ['billing_issue', 'price_increase_consent'] },
});

Nếu không có filter, SDK sẽ hiển thị tất cả các thông báo đang chờ, kể cả những loại mà nó không nhận ra. Truyền mảng rỗng sẽ không hiển thị thông báo nào. Android bỏ qua filter và yêu cầu tất cả thông báo Google Play.

Lỗi

Trên iOS, showStoreMessages sẽ throw một AdaptyError với một trong các mã lỗi sau:

CodeTênNguyên nhân
2006decodingFailedThiết bị đang chạy iOS 15 trở xuống. Chỉ gọi phương thức này trên iOS 16 trở lên.
3201operationInProgressMột lệnh gọi showStoreMessages khác vẫn đang hiển thị thông báo, và lệnh gọi này cũng có thông báo cần hiển thị. Hãy đợi lệnh gọi đầu tiên hoàn tất rồi thử lại.
3202resolverFailureSDK không tìm thấy window scene nào đang hoạt động ở foreground để hiển thị thông báo. Các thông báo đã hiển thị trước khi xảy ra lỗi sẽ được xóa khỏi danh sách chờ. Gọi lại phương thức khi ứng dụng đang ở foreground để hiển thị phần còn lại.