Cài đặt & cấu hình Android SDK

SDK Adapty bao gồm hai module chính để tích hợp liền mạch vào ứng dụng di động của bạn:

• Core Adapty: Đây là SDK bắt buộc để Adapty hoạt động đúng trong ứng dụng của bạn.
• AdaptyUI: Module này cần thiết nếu bạn sử dụng Adapty Paywall Builder — công cụ no-code thân thiện với người dùng để tạo paywall đa nền tảng một cách dễ dàng. AdaptyUI được tự động kích hoạt cùng với module core.

Yêu cầu

Yêu cầu SDK tối thiểu: minSdkVersion 21

Cài đặt Adapty SDK

Chọn phương thức thiết lập dependency của bạn:

• Gradle tiêu chuẩn: Thêm dependency vào file build.gradle ở cấp module
• Nếu dự án của bạn dùng file .gradle.kts, thêm dependency vào file build.gradle.kts cấp module
• Nếu bạn dùng version catalog, thêm dependency vào file libs.versions.toml, sau đó tham chiếu nó trong build.gradle.kts

dependencies {
    ...
    implementation platform('io.adapty:adapty-bom:<the latest SDK version>')
    implementation 'io.adapty:android-sdk'
    
    // Only add this line if you plan to use Paywall Builder
    implementation 'io.adapty:android-ui'
}

dependencies {
    ...
    implementation(platform("io.adapty:adapty-bom:<the latest SDK version>"))
    implementation("io.adapty:android-sdk")
    
    // Chỉ thêm dòng này nếu bạn có kế hoạch sử dụng Paywall Builder:
    implementation("io.adapty:android-ui")
}

//libs.versions.toml

[versions]
..
adaptyBom = "<the latest SDK version>"

[libraries]
..
adapty-bom = { module = "io.adapty:adapty-bom", version.ref = "adaptyBom" }
adapty = { module = "io.adapty:android-sdk" }

// Only add this line if you plan to use Paywall Builder:
adapty-ui = { module = "io.adapty:android-ui" }

//module-level build.gradle.kts

dependencies {
    ...
    implementation(platform(libs.adapty.bom))
    implementation(libs.adapty)
    
    // Only add this line if you plan to use Paywall Builder:
    implementation(libs.adapty.ui)
}

Nếu dependency không được resolve, hãy đảm bảo rằng bạn đã có mavenCentral() trong Gradle scripts.

allprojects {
    repositories {
        ...
        mavenCentral()
    }
}

dependencyResolutionManagement {
    ...
    repositories {
        ...
        mavenCentral()
    }
}

Kích hoạt module Adapty của Adapty SDK

Thiết lập cơ bản

Kích hoạt Adapty SDK trong code của ứng dụng.

Để lấy Public SDK Key:

1. Truy cập Adapty Dashboard và điều hướng đến App settings → General.
2. Trong phần Api keys, sao chép Public SDK Key (KHÔNG phải Secret Key).
3. Thay thế "YOUR_PUBLIC_SDK_KEY" trong code.

Hoặc lấy theo cách lập trình, sử dụng Adapty CLI:

npm install -g adapty
adapty auth login
adapty apps list

Hoặc, trực tiếp:

npx adapty auth login
adapty apps list

• Đảm bảo bạn sử dụng Public SDK key để khởi tạo Adapty, Secret key chỉ nên dùng cho server-side API.
• SDK keys là duy nhất cho mỗi ứng dụng, vì vậy nếu bạn có nhiều ứng dụng, hãy đảm bảo chọn đúng key.

// In your Application class

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Adapty.activate(
            applicationContext,
            AdaptyConfig.Builder("PUBLIC_SDK_KEY")
                .build()
        )
    }
}

// In your Application class

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Adapty.activate(
            getApplicationContext(),
            new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
                .build()
        );
    }
}

Bây giờ hãy thiết lập paywall trong ứng dụng của bạn:

• Nếu bạn dùng Adapty Paywall Builder, hãy làm theo hướng dẫn nhanh về Paywall Builder.
• Nếu bạn tự xây dựng giao diện paywall, hãy xem hướng dẫn nhanh cho paywall tùy chỉnh.

Kích hoạt module AdaptyUI của Adapty SDK

Nếu bạn có kế hoạch sử dụng Paywall Builder, bạn cần module AdaptyUI. Module này được kích hoạt tự động khi bạn kích hoạt module cốt lõi; bạn không cần thực hiện thêm bất cứ điều gì.

Cấu hình Proguard

Trước khi phát hành ứng dụng lên production, hãy thêm -keep class com.adapty.** { *; } vào cấu hình Proguard của bạn.

Thiết lập tùy chọn

Ghi log

Thiết lập hệ thống ghi log

Adapty ghi lại các lỗi và thông tin quan trọng khác để giúp bạn hiểu chuyện gì đang xảy ra. Có các cấp độ log sau:

Adapty.logLevel = AdaptyLogLevel.VERBOSE 
//recommended for development and the first production release

Adapty.setLogLevel(AdaptyLogLevel.VERBOSE);
//recommended for development and the first production release

Chuyển hướng thông báo từ hệ thống logging

Nếu vì lý do nào đó bạn cần gửi thông báo từ Adapty đến hệ thống của mình hoặc lưu vào file, bạn có thể ghi đè hành vi mặc định:

Adapty.setLogHandler { level, message ->
    //handle the log
}

Adapty.setLogHandler((level, message) -> {
    //handle the log
});

Chính sách dữ liệu

Adapty không lưu trữ dữ liệu cá nhân của người dùng trừ khi bạn tự gửi lên, nhưng bạn có thể áp dụng thêm các chính sách bảo mật dữ liệu để tuân thủ các quy định của cửa hàng hoặc từng quốc gia.

Tắt thu thập và chia sẻ địa chỉ IP

Khi kích hoạt module Adapty, đặt ipAddressCollectionDisabled thành true để tắt tính năng thu thập và chia sẻ địa chỉ IP của người dùng. Giá trị mặc định là false. Sử dụng tham số này để tăng cường quyền riêng tư của người dùng, tuân thủ các quy định bảo vệ dữ liệu theo khu vực (như GDPR hoặc CCPA), hoặc giảm thiểu việc thu thập dữ liệu không cần thiết khi ứng dụng của bạn không yêu cầu các tính năng dựa trên IP.

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withIpAddressCollectionDisabled(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withIpAddressCollectionDisabled(true)
    .build();

Vô hiệu hóa thu thập và chia sẻ advertising ID (Ad ID)

Khi kích hoạt module Adapty, đặt adIdCollectionDisabled thành true để tắt tính năng thu thập advertising ID của người dùng. Giá trị mặc định là false. Sử dụng tham số này để tuân thủ chính sách của Play Store, tránh kích hoạt lời nhắc cấp quyền advertising ID, hoặc nếu ứng dụng của bạn không cần attribution quảng cáo hay phân tích dựa trên Ad ID.

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdIdCollectionDisabled(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdIdCollectionDisabled(true)
    .build();

Thiết lập cấu hình cache media cho AdaptyUI

Theo mặc định, AdaptyUI lưu cache media (như hình ảnh và video) để cải thiện hiệu suất và giảm lưu lượng mạng. Bạn có thể tùy chỉnh cài đặt cache bằng cách cung cấp một cấu hình tùy chỉnh. Sử dụng AdaptyUI.configureMediaCache để ghi đè kích thước cache mặc định và thời gian hiệu lực. Đây là tùy chọn không bắt buộc—nếu bạn không gọi phương thức này, các giá trị mặc định sẽ được sử dụng (dung lượng đĩa 100MB, hiệu lực 7 ngày).

val cacheConfig = MediaCacheConfiguration.Builder()
    .overrideDiskStorageSizeLimit(200L * 1024 * 1024) // 200 MB
    .overrideDiskCacheValidityTime(3.days)
    .build()

AdaptyUI.configureMediaCache(cacheConfig)

MediaCacheConfiguration cacheConfig = new MediaCacheConfiguration.Builder()
    .overrideDiskStorageSizeLimit(200L * 1024 * 1024) // 200 MB
    .overrideDiskCacheValidityTime(TimeInterval.days(3))
    .build();

AdaptyUI.configureMediaCache(cacheConfig);

Tham số:

Đặt obfuscated account ID

Google Play yêu cầu obfuscated account ID cho một số trường hợp sử dụng nhất định nhằm tăng cường quyền riêng tư và bảo mật cho người dùng. Các ID này giúp Google Play xác định các giao dịch mua trong khi vẫn giữ thông tin người dùng ẩn danh — điều này đặc biệt quan trọng để phòng chống gian lận và phân tích dữ liệu.

Bạn có thể cần đặt các ID này nếu ứng dụng của bạn xử lý dữ liệu người dùng nhạy cảm hoặc nếu bạn phải tuân thủ các quy định về quyền riêng tư cụ thể. Obfuscated ID cho phép Google Play theo dõi các giao dịch mua mà không lộ định danh người dùng thực.

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withObfuscatedAccountId("YOUR_OBFUSCATED_ACCOUNT_ID")
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withObfuscatedAccountId("YOUR_OBFUSCATED_ACCOUNT_ID")
    .build();

Chạy Adapty trong một tiến trình tùy chỉnh

Theo mặc định, Adapty chỉ có thể chạy trong tiến trình chính của ứng dụng. Nếu ứng dụng của bạn sử dụng nhiều tiến trình, hãy khởi tạo Adapty chỉ một lần; nếu không, có thể xảy ra hành vi không mong muốn.

Nếu bạn cần chạy Adapty trong một tiến trình khác, hãy chỉ định nó trong cấu hình:

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withProcessName(":custom")
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withProcessName(":custom")
    .build();

Nếu bạn cố kích hoạt Adapty trong một process khác mà không thiết lập giá trị này, SDK sẽ ghi log cảnh báo và bỏ qua việc kích hoạt.

Bật mức độ truy cập cục bộ

Theo mặc định, mức độ truy cập cục bộ bị tắt trên Android. Để bật chúng, hãy đặt withLocalAccessLevelAllowed thành true:

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withLocalAccessLevelAllowed(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withLocalAccessLevelAllowed(true)
    .build();

Khắc phục sự cố

Quy tắc sao lưu Android (cấu hình Auto Backup)

Một số SDK (bao gồm Adapty) đi kèm với cấu hình Android Auto Backup riêng. Nếu bạn sử dụng nhiều SDK đều định nghĩa quy tắc sao lưu, quá trình merge Android manifest có thể thất bại với lỗi liên quan đến android:fullBackupContent, android:dataExtractionRules, hoặc android:allowBackup.

Dấu hiệu lỗi thường gặp: Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/sample_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules) Để giải quyết vấn đề này, bạn cần:

• Yêu cầu manifest merger sử dụng giá trị của ứng dụng cho các thuộc tính liên quan đến backup.

• Gộp các quy tắc backup từ Adapty và các SDK khác vào một file XML duy nhất (hoặc một cặp file cho Android 12+).

1. Thêm namespace tools vào manifest của bạn

Nếu chưa có, hãy thêm namespace tools vào thẻ gốc <manifest>:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. Ghi đè các thuộc tính backup trong <application>

Trong file AndroidManifest.xml của ứng dụng, hãy cập nhật thẻ <application> để ứng dụng của bạn cung cấp các giá trị cuối cùng và yêu cầu manifest merger thay thế các giá trị từ thư viện:

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

Nếu SDK nào đó cũng thiết lập android:allowBackup, hãy thêm nó vào tools:replace:

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. Tạo các file quy tắc backup đã hợp nhất

Tạo các file XML trong thư mục app/src/main/res/xml/ để kết hợp các quy tắc của Adapty với quy tắc từ các SDK khác. Android sử dụng các định dạng quy tắc backup khác nhau tùy theo phiên bản hệ điều hành, vì vậy việc tạo cả hai file đảm bảo khả năng tương thích trên tất cả các phiên bản Android mà ứng dụng của bạn hỗ trợ.

Đối với Android 12 trở lên (sử dụng định dạng quy tắc trích xuất dữ liệu mới):

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

Đối với Android 11 trở xuống (sử dụng định dạng nội dung full backup cũ):

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

    
    
</full-backup-content>

Với cấu hình này:

• Các mục loại trừ backup của Adapty (AdaptySDKPrefs.xml) được giữ nguyên.

• Các mục loại trừ của SDK khác (ví dụ: appsflyer-data) cũng được áp dụng.

• Manifest merger sử dụng cấu hình ứng dụng của bạn và không còn báo lỗi về các thuộc tính backup xung đột nữa.

Giao dịch mua thất bại sau khi quay lại từ ứng dụng khác

Nếu Activity khởi động flow mua hàng sử dụng launchMode không phải mặc định, Android có thể tạo lại hoặc tái sử dụng Activity đó không đúng cách khi người dùng quay lại từ Google Play, ứng dụng ngân hàng, hoặc trình duyệt. Điều này có thể khiến kết quả giao dịch bị mất hoặc bị xử lý như đã hủy.

Để đảm bảo giao dịch mua hoạt động đúng, chỉ sử dụng chế độ khởi chạy standard hoặc singleTop cho Activity khởi động flow mua hàng, và tránh các chế độ khác. Trong AndroidManifest.xml của bạn, hãy đảm bảo Activity khởi động flow mua hàng được đặt thành standard hoặc singleTop:

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />