Migration từ RevenueCat gồm tám bước. Một coding agent sẽ làm phần lớn công việc: chạy migration qua Adapty CLI và thay thế RevenueCat SDK trong app của bạn. Bạn xử lý những phần mà agent không thể tiếp cận — các secret, và các cài đặt trong RevenueCat, App Store Connect, và Google Cloud.

1. Tìm hiểu những khác biệt cốt lõi.
2. Chuyển danh mục sản phẩm sang Adapty.
3. Chuyển thiết kế paywall, nếu offerings của bạn trở thành flow.
4. Thay thế RevenueCat SDK bằng coding agent của bạn.
5. Chuyển các tích hợp.
6. Chuyển tiếp sự kiện từ cửa hàng sang Adapty.
7. Kiểm thử và phát hành phiên bản mới của ứng dụng.
8. (Tùy chọn) Import lịch sử giao dịch.

Trước khi phát hành phiên bản mới của ứng dụng có tích hợp Adapty SDK, hãy kiểm tra danh sách kiểm tra trước khi phát hành của chúng tôi.

Tìm hiểu những điểm khác biệt cơ bản

Adapty và RevenueCat SDK được thiết kế theo cách tương tự nhau. Điểm khác biệt lớn nhất là về mức sử dụng mạng và tốc độ: Adapty SDK được thiết kế để cung cấp thông tin theo yêu cầu nhanh nhất có thể khi bạn cần. Ví dụ, khi yêu cầu một paywall, bạn nhận được Remote Config trước để dựng sẵn onboarding hoặc paywall, sau đó mới gửi yêu cầu riêng để lấy sản phẩm.

Tên gọi có một chút khác biệt:

RevenueCat	Adapty
Package	Sản phẩm
Offering	Paywall
Paywall	Flow
Entitlement	Mức độ truy cập

Adapty có khái niệm placement. Đây là vị trí logic trong ứng dụng nơi người dùng có thể thực hiện mua hàng. Trong hầu hết các trường hợp, bạn sẽ có một hoặc hai placement:

• Onboarding (vì 80% giao dịch mua hàng diễn ra ở đây);
• General (hiển thị trong phần cài đặt hoặc bên trong ứng dụng sau onboarding).

Chuyển danh mục của bạn sang Adapty

Quá trình migration danh mục sẽ tạo một ứng dụng Adapty mới từ dự án RevenueCat của bạn: mức độ truy cập từ các entitlement, sản phẩm từ các package, và một placement kèm paywall hoặc flow cho mỗi offering.

Trước khi bắt đầu

• Sử dụng một coding agent có thể chạy lệnh terminal, ví dụ Claude Code, Codex, hoặc Cursor.
• Trong terminal mà agent của bạn sử dụng, cài đặt Adapty CLI và đăng nhập.
• Trong RevenueCat, tạo secret API key (v2) cho dự án bạn muốn migrate.
• Kiểm tra các cửa hàng. Migration chỉ áp dụng cho các ứng dụng trên App Store và Google Play.

Tạo RevenueCat secret API key

Adapty đọc catalog RevenueCat của bạn bằng secret API key của project bạn cần migrate. Secret key trong RevenueCat thuộc về một project cụ thể, vì vậy hãy tạo key trong project đó.

1. Để mở danh sách key, trong RevenueCat dashboard, mở project rồi vào API keys.
2. Để tạo key, nhấn New secret API key.
3. Để thiết lập key, nhập tên, ví dụ Adapty migration, và chọn V2 trong API version.
4. Để cho phép Adapty đọc catalog, đặt Project configuration permissions thành Read only. Adapty không cần các quyền khác.
5. Để tạo key, nhấn Generate, rồi sao chép lại.

Khi quá trình migration yêu cầu khóa, hãy dán nó vào trang Adapty Dashboard mở ra.

Chạy migration catalog

1. Để bắt đầu migration, hãy yêu cầu agent của bạn:

   Migrate my RevenueCat project to a new Adapty app called "Acme Fitness" with the Adapty CLI.

2. Để kết nối RevenueCat, dán secret API key vào trang Adapty Dashboard mà agent mở ra. Key được gửi thẳng đến Adapty và không đi qua agent hay CLI.

3. Để chọn nội dung cần migrate, hãy cho agent biết những app RevenueCat nào thuộc về nhau — thường là một app mỗi nền tảng của cùng một sản phẩm. Chúng sẽ được gộp thành một app Adapty duy nhất.

4. Để hoàn tất ánh xạ, hãy trả lời các câu hỏi của agent về những entity mà Adapty không tự ánh xạ được. Với mỗi offering, hãy chọn placement đó chứa gì: một paywall do app của bạn tự vẽ, hay một flow từ Flow & Paywall Builder. Adapty sẽ gợi ý flow cho các offering đã có RevenueCat paywall.

   Warning

   Quyết định là cuối cùng. Khi mọi thực thể đã có quyết định, Adapty sẽ tạo danh mục và bạn không thể thay đổi ánh xạ sau đó.

   Adapty tạo mức độ truy cập, sản phẩm, paywall và flow, cùng các placement theo thứ tự đó. Nếu một số trong số chúng thất bại, agent sẽ cho bạn biết lý do. Khi mọi thực thể đã có trong Adapty, quá trình migration hoàn tất.

5. Để ứng dụng mới có thể xác thực các giao dịch mua, hãy kết nối nó với các cửa hàng trong Adapty Dashboard: App Store và Google Play.

Cách ánh xạ các thực thể RevenueCat sang Adapty

• Mã định danh entitlement trở thành ID mức độ truy cập, vì vậy customerInfo.entitlements["premium"] trở thành profile.accessLevels["premium"].
• Sản phẩm không gắn với entitlement nào sẽ cấp mức độ truy cập premium.
• Mã định danh offering trở thành ID placement.
• Metadata của offering trở thành Remote Config của paywall hoặc flow, tối đa 256 KB.

Danh mục migration không bao gồm những gì

• Các offering không có sản phẩm.
• Các sản phẩm có App Store product ID mà Adapty từ chối, ví dụ ID chứa dấu hai chấm hoặc dấu cách. Agent sẽ thông báo cho bạn biết những sản phẩm nào bị ảnh hưởng và bạn không cần đưa ra quyết định gì.
• Các ứng dụng trên cửa hàng khác ngoài App Store và Google Play.
• Integrations: Di chuyển chúng riêng.

Di chuyển thiết kế paywall của bạn

Mỗi flow mà quá trình migration danh mục tạo ra đều được xuất bản với một màn hình trống hiển thị các sản phẩm của offering. Để xây dựng lại thiết kế paywall RevenueCat của bạn trong các flow này, hãy yêu cầu agent của bạn:

Migrate my RevenueCat paywall designs to my Adapty app "Acme Fitness" with the Adapty CLI.

Agent sẽ xây dựng lại từng flow một và xuất bản mỗi flow sau khi bạn phê duyệt. Agent sẽ liệt kê những gì bạn cần tự thêm vào, chẳng hạn như video và phông chữ tùy chỉnh. Agent đọc các thiết kế bằng RevenueCat secret API key của bạn, vì vậy hãy giữ lại key cho đến khi các thiết kế được di chuyển xong.

Thay thế RevenueCat SDK

Một coding agent sẽ thay thế RevenueCat SDK bằng Adapty SDK trong code của ứng dụng, sử dụng các ID từ catalog mà quá trình migration đã tạo ra. Mỗi lần chạy sẽ migrate một codebase: nếu ứng dụng có dự án iOS và Android riêng biệt, hãy chạy agent trong từng dự án.

Trước khi bắt đầu, hãy commit hoặc stash các thay đổi trong repository của ứng dụng, để migration chỉ tạo ra một diff duy nhất dễ review.

1. Để bắt đầu migration code, mở agent tại thư mục gốc của repository ứng dụng và nhập:

   Migrate the app code in this repository from RevenueCat to Adapty with the Adapty CLI, for my Adapty app "Acme Fitness".

   Nếu agent yêu cầu bạn khởi động lại để tải các Adapty skill, hãy khởi động lại và lặp lại yêu cầu.

2. Nếu thiết kế của một flow chưa được chuyển đổi, hãy cho agent biết liệu ứng dụng có hiển thị flow đó hay giữ nguyên màn hình paywall của nó cho đến khi hoàn thành.

3. Để hoàn tất quá trình migration code, hãy xem lại các thay đổi trên nhánh adapty-migrate, sau đó xem qua ADAPTY_SETUP.md ở thư mục gốc của dự án. File này liệt kê những gì agent đã để lại cho bạn.

Chuyển đổi các tích hợp của bạn

Agent sẽ tìm các công cụ analytics, attribution và messaging trong code ứng dụng của bạn, rồi hướng dẫn cách thiết lập từng công cụ trong Adapty. Agent không thay đổi bất kỳ tệp nào. Hãy hỏi:

Find the integrations in my app code to set up in my Adapty app "Acme Fitness", with the Adapty CLI.

Nếu repository chỉ chứa code của một nền tảng, hãy cho agent biết nền tảng còn lại ở đâu. Sau đó, thiết lập các tích hợp như mô tả trong Migrate tích hợp sang Adapty. Webhook, Slack và xuất cloud storage không nằm trong code ứng dụng: hãy tìm chúng trên trang Integrations trong RevenueCat.

Chuyển tiếp sự kiện cửa hàng đến Adapty

App Store và Google Play gửi thông báo về các sự kiện gia hạn, hủy và hoàn tiền đến máy chủ của bạn, kể cả những sự kiện xảy ra bên ngoài ứng dụng. Hai migrations kết nối Adapty với các thông báo này trong khi RevenueCat vẫn tiếp tục nhận mọi sự kiện, để cả hai đều được cập nhật trong khi người dùng chuyển sang phiên bản ứng dụng mới.

Bắt đầu sau khi hoàn tất migration catalog. Adapty lấy bundle ID và package name từ các ứng dụng RevenueCat bạn đã chọn ở đó.

Chuyển tiếp sự kiện App Store

Adapty nhận thông báo từ App Store và chuyển tiếp từng thông báo đó đến RevenueCat.

Trước khi bắt đầu, hãy tạo một In-App Purchase key trong App Store Connect và ghi lại Issuer ID và Key ID của nó.

1. Để bắt đầu chuyển tiếp, hãy yêu cầu agent của bạn:

   Forward App Store events for my Adapty app "Acme Fitness" to Adapty, and keep RevenueCat receiving them.

2. Để cấp quyền truy cập App Store events cho Adapty, trên trang Adapty Dashboard mà agent mở ra, hãy tải lên file .p8, nhập Issuer ID và Key ID. Key được gửi thẳng đến Adapty mà không đi qua agent hay CLI.

3. Để RevenueCat tiếp tục nhận App Store events, hãy cung cấp cho agent URL thông báo của RevenueCat. Trong RevenueCat, mở ứng dụng iOS của bạn, sau đó sao chép Apple Server Notification URL từ Apple Server to Server notification settings. URL này bắt đầu bằng https://api.revenuecat.com/v1/incoming-webhooks/.

4. Để trỏ App Store về Adapty, trong App Store Connect, mở ứng dụng của bạn, rồi vào App Information > App Store Server Notifications. Đặt cả Production Server URL và Sandbox Server URL thành URL Adapty mà agent cung cấp, với thông báo Version 2. Xem chi tiết tại Bật thông báo server App Store. Lúc này việc chuyển tiếp sang RevenueCat đã được bật, nên không có event nào bị mất.

5. Để kiểm tra kết nối, hãy thông báo cho agent rằng các URL đã được thiết lập. Adapty sẽ yêu cầu App Store gửi một thông báo kiểm tra và chờ nhận. Nếu thông báo không đến, agent sẽ cho bạn biết nguyên nhân.

Chuyển tiếp sự kiện Google Play

Google Play gửi thông báo đến một Pub/Sub topic. Adapty đăng ký vào topic mà RevenueCat đang dùng với tư cách là subscriber thứ hai, để RevenueCat tiếp tục nhận sự kiện.

1. Để bắt đầu chuyển tiếp, hãy hỏi agent của bạn:

   Forward Google Play events for my Adapty app "Acme Fitness" to Adapty, and keep RevenueCat receiving them.

2. Để cấp quyền truy cập cho Adapty vào topic, hãy tạo JSON key cho service account mà RevenueCat đang sử dụng. Trong Google Cloud console, vào IAM & Admin > Service Accounts, mở tài khoản (thường là revenuecat-service-account), sau đó vào Keys > Add key và chọn JSON. Việc tạo key mới không ảnh hưởng đến RevenueCat. Xem thêm hướng dẫn của Google về cách tạo service account key.

3. Để tải key lên, trong trang Adapty Dashboard mà agent mở, hãy tải file lên ô Google Play service account key (JSON). Key sẽ được gửi thẳng đến Adapty và không đi qua agent hay CLI.

4. Để đăng ký Adapty nhận thông báo từ topic, hãy cung cấp ID của topic cho agent. Trong RevenueCat, mở cài đặt ứng dụng Google Play của bạn, sau đó sao chép Topic ID từ mục Google developer notifications. Google Play Console cũng hiển thị giá trị này tại Monetize > Monetization setup > Topic name.

   Adapty đăng ký theo dõi topic, sau đó xuất bản một thông báo kiểm tra và chờ nhận nó. Nếu thông báo không đến, agent sẽ cho bạn biết lý do.

5. Nếu quá trình kiểm tra thất bại do lỗi quyền, hãy cấp cho service account vai trò Pub/Sub Editor trong project của topic, hoặc vai trò Pub/Sub Subscriber trên topic và Pub/Sub Editor trong project của key. Sau đó yêu cầu agent kiểm tra lại.

Kiểm tra và phát hành phiên bản mới của ứng dụng

Nếu bạn đang đọc phần này, bạn đã hoàn thành:

• Chuyển danh mục sản phẩm sang Adapty
• Chuyển thiết kế paywall, nếu bạn sử dụng flow
• Thay thế SDK RevenueCat bằng Adapty
• Hoàn thành các bước trong ADAPTY_SETUP.md từ coding agent của bạn
• Thiết lập các tích hợp trong Adapty
• Chuyển tiếp sự kiện từ App Store và Google Play sang Adapty
• Thực hiện mua hàng trong sandbox
• Phát hành phiên bản mới của ứng dụng

Nếu bạn đã hoàn thành các điểm trên, hãy thực hiện một giao dịch mua thử trong Sandbox rồi phát hành ứng dụng.

(Tùy chọn) Nhập lịch sử giao dịch của bạn

Việc nhập dữ liệu sẽ điền vào hồ sơ người dùng và biểu đồ lịch sử thanh toán của người dùng. Việc này không ảnh hưởng đến quyền truy cập của bất kỳ ai.

Hai migration sẽ nhập lịch sử vào ứng dụng mà quá trình migration danh mục của bạn đã tạo. Hãy sử dụng Cloud Export nếu gói RevenueCat của bạn hỗ trợ tính năng này.

Với RevenueCat Cloud Export

RevenueCat gửi một bản export hàng ngày vào bucket mà Adapty chuẩn bị cho ứng dụng của bạn, và Adapty import mọi file nhận được.

1. Để bắt đầu import, hãy yêu cầu agent của bạn:

   Import the RevenueCat transaction history into my Adapty app "Acme Fitness" with a Cloud Export.

2. Để kết nối export, hãy cung cấp cho agent External ID từ RevenueCat. Trong RevenueCat, mở cài đặt Scheduled Data Exports, chọn IAM Role (ARN) làm loại thông tin xác thực, và sao chép External ID mà RevenueCat hiển thị. External ID không phải là thông tin bí mật.

3. Để hoàn tất cài đặt export, trong RevenueCat, nhập bucket, region và role ARN mà agent cung cấp cho bạn. Bật Receive new and updated transactions only. Nếu không, RevenueCat sẽ export toàn bộ lịch sử mỗi ngày, và Adapty sẽ import mọi file.

RevenueCat có thể mất tới 24 giờ để gửi file đầu tiên, và Adapty kiểm tra các file mới trong bucket mỗi giờ một lần. Quá trình migration sẽ tự động hoàn tất sau một tuần kể từ khi Adapty import file đầu tiên. Customer User ID của mỗi hồ sơ người dùng được import là rc_last_seen_app_user_id_alias.

Thông qua bộ phận hỗ trợ

Sử dụng cách này nếu gói RevenueCat của bạn không có Cloud Export: bộ phận hỗ trợ RevenueCat gửi cho bạn bản xuất dữ liệu, và bộ phận hỗ trợ Adapty sẽ nhập dữ liệu đó vào.

1. Để bắt đầu quá trình nhập, hãy yêu cầu agent của bạn:

   Import the RevenueCat transaction history into my Adapty app "Acme Fitness" through support.

2. Để yêu cầu xuất dữ liệu, hãy gửi cho bộ phận hỗ trợ của RevenueCat tin nhắn đầu tiên trong hai tin nhắn mà agent cung cấp cho bạn.

3. Để import dữ liệu, hãy chuyển tiếp các file RevenueCat gửi cho bạn đến bộ phận hỗ trợ của Adapty kèm theo tin nhắn thứ hai. Đính kèm các file đúng như RevenueCat đã gửi: việc mở, lưu lại hoặc gộp chúng sẽ làm thay đổi định dạng cột mà quá trình import yêu cầu.

Dữ liệu nào sẽ được import

Dữ liệu sau đây sẽ được import vào Adapty cho mỗi giao dịch:

Tham số	Mô tả
user_id	Customer User ID, định danh chính của người dùng trong Adapty và hệ thống của bạn.
apple_original_transaction_id	Đối với chuỗi gói đăng ký, đây là ngày mua của giao dịch gốc, được liên kết qua store_original_transaction_id.
google_product_id	ID sản phẩm trên Google Play Store.
google_purchase_token	Định danh duy nhất do Google Play cung cấp cho mỗi giao dịch, cần thiết để xác thực.
country	Quốc gia của người dùng.
created_at	Ngày và giờ tạo người dùng.
subscription_expiration_date	Ngày và giờ gói đăng ký hết hạn.
email	Email của người dùng cuối.
phone_number	Số điện thoại của người dùng cuối.
idfa	Identifier for Advertisers (IDFA), do Apple gán cho thiết bị của người dùng.
idfv	Identifier for Vendors (IDFV), mã được gán cho tất cả ứng dụng của một nhà phát triển và dùng chung trên các ứng dụng đó trong một thiết bị.
advertising_id	Định danh duy nhất do Android OS cung cấp, dùng cho mục đích theo dõi của nhà quảng cáo.
attribution_channel	Tên kênh marketing.
attribution_campaign	Tên chiến dịch marketing.
attribution_ad_group	Nhóm quảng cáo attribution.
attribution_ad_set	Bộ quảng cáo attribution.
attribution_creative	Từ khóa creative attribution.

Ngoài ra, các mã định danh tích hợp cho các tích hợp sau sẽ được nhập: Amplitude, Mixpanel, AppsFlyer, Adjust và FacebookAds.

Những gì không được truyền tải

• Mỗi giao dịch đều được xác minh lại với cửa hàng trong quá trình import, vì vậy các hàng mà cửa hàng không còn nhận ra sẽ bị bỏ qua.
• Các hàng không có ID giao dịch thực từ cửa hàng — ví dụ như entitlement được cấp thủ công hoặc ưu đãi của RevenueCat — sẽ được import dưới dạng hồ sơ người dùng không có giao dịch. Để khôi phục quyền truy cập cho những người dùng này, hãy cấp cho họ mức độ truy cập thông qua server-side API.
• Lịch sử hoàn tiền và sự cố thanh toán không được chuyển nguyên vẹn: hoàn tiền chỉ giữ lại ngày hủy, còn trạng thái sự cố thanh toán của gói đăng ký được ghi nhận tại thời điểm import, không kèm theo ngày lịch sử.

Câu hỏi thường gặp

Tôi đã cài đặt thành công Adapty SDK và phát hành phiên bản ứng dụng mới. Điều gì sẽ xảy ra với những người dùng cũ chưa cập nhật lên phiên bản có Adapty SDK?

Hầu hết người dùng sạc điện thoại qua đêm — đó là lúc App Store thường tự động cập nhật tất cả ứng dụng, vì vậy đây không phải vấn đề đáng lo ngại. Vẫn có thể có một số ít người dùng trả phí chưa cập nhật, nhưng họ vẫn có quyền truy cập vào nội dung premium. Bạn không cần lo lắng và không cần ép họ cập nhật.

Tôi có cần xuất dữ liệu lịch sử từ RevenueCat càng sớm càng tốt không, hay tôi sẽ mất dữ liệu đó?

Bạn không cần phải làm gấp; hãy phát hành phiên bản ứng dụng với Adapty SDK trước, sau đó mới import lịch sử. Chúng tôi sẽ khôi phục lịch sử thanh toán của người dùng và điền đầy đủ vào hồ sơ người dùng và biểu đồ.

Tôi đang dùng MMP (AppsFlyer, Adjust, v.v.) và analytics (Mixpanel, Amplitude, v.v.). Làm sao để đảm bảo mọi thứ hoạt động đúng?

Trước tiên, bạn cần truyền cho chúng tôi các ID của các dịch vụ bên thứ ba đó qua SDK để chúng tôi có thể gửi dữ liệu tới chúng. Đọc hướng dẫn về tích hợp attribution và tích hợp analytics. Đối với dữ liệu lịch sử và người dùng cũ, hãy đảm bảo bạn truyền cho chúng tôi các ID đó từ dữ liệu bạn đã xuất từ RevenueCat.