Help Center

YÊU CẦU DEMO
Help CenterApp pushCài đặt thư viện Mobio SDK cho hệ điều hành Android
Cài đặt thư viện Mobio SDK cho hệ điều hành Android

1. Định nghĩa & Giá trị

Tổng quan: Đây là bước cấu hình nền tảng đầu tiên để đưa bộ công cụ Mobio SDK vào source code ứng dụng Android của bạn. Quá trình này bao gồm việc nhúng file thư viện vật lý (.aar) vào dự án và cấu hình lớp Application để chuẩn bị cho việc khởi tạo.

Lợi ích/ Giá trị:

  • Đảm bảo ứng dụng Android có đầy đủ các package cần thiết để sẵn sàng giao tiếp với hệ thống Mobio CDP.
  • Việc cấu hình chuẩn xác lớp Application trong Manifest ngay từ đầu giúp SDK có thể theo dõi hành vi người dùng xuyên suốt toàn bộ vòng đời của ứng dụng mà không bị gián đoạn.

Đối tượng thao tác: Android Developer.

2. Giải thích Thuật ngữ & Thông số

  • File .aar (Android Archive): Định dạng đóng gói thư viện chuẩn của Android, chứa các file mã nguồn (compiled code) và tài nguyên (resources) của Mobio SDK.
  • build.gradle (Module: app): File cấu hình của Gradle dùng để khai báo các thư viện phụ thuộc (dependencies) cho dự án Android.
  • AndroidManifest.xml: File khai báo các thành phần cốt lõi của ứng dụng (như Application, Activity, Service) và các quyền (Permissions) với hệ điều hành Android.

3. Điều kiện tiên quyết (Prerequisite)

4. Các bước thực hiện

Bước 1: Thêm file Mobio SDK (.aar) vào dự án

Mobio SDK cho Android hiện được phân phối dưới dạng file .aar nội bộ. Bạn thực hiện đưa file này vào source code như sau:

  1. Tạo một thư mục tên là libs trong folder root của project (ví dụ: root_project/libs) nếu chưa có.
  2. Sao chép file mobio-sdk.aar nhận được vào thư mục root_project/libs.

Bước 2: Cấu hình build.gradle

Mở file cấu hình của module app (thường là app/build.gradle hoặc app/build.gradle.kts) và thực hiện các thay đổi sau:

2.1. Thêm SDK từ thư mục libs

Trong phần dependencies, thêm dòng sau để ứng dụng nhận diện file .aar:

Groovy DSL

dependencies {
    // ... các dependencies khác
    implementation files("libs/mobio-sdk.aar")
}

Kotlin DSL

dependencies {
    // ... các dependencies khác
    implementation(files("libs/mobio-sdk.aar"))
}

2.2. Khai báo các thư viện phụ thuộc (Dependencies)

Mobio SDK cần các thư viện của Google và Firebase để hoạt động. Thêm các dòng sau vào block dependencies:

Với dự án viết bằng Java
dependencies {
        // ...
        // Core Android
        implementation 'androidx.appcompat:appcompat:1.7.0'
        implementation 'androidx.work:work-runtime:2.9.0'

        // Firebase (cho push notification)
        implementation platform('com.google.firebase:firebase-bom:32.2.2')
        implementation 'com.google.firebase:firebase-messaging'

        // Utilities
        implementation 'com.google.code.gson:gson:2.10.1'
        implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
    }
Với dự án viết bằng Kotlin
Cách 1: Sử dụng Version Catalog (Khuyên dùng)

Đây là cách quản lý phiên bản tập trung, giúp tránh xung đột và dễ nâng cấp.

Bước 1: Cập nhật file gradle/libs.versions.toml

Thêm các khai báo sau vào các mục tương ứng:

Ini, TOML

[versions]# ... giữ nguyên các phiên bản cũ và thêm các dòng dưới đây
workRuntime = "2.9.0"
firebaseBom = "32.2.2"
gson = "2.10.1"
playServicesAdsIdentifier = "18.0.1"

[libraries]
# Core Android & WorkManager
androidx-work-runtime-ktx = { group = "androidx.work", name = "work-runtime-ktx", version.ref = "workRuntime" }

# Firebase (Quản lý qua BOM)
firebase-bom = { group = "com.google.firebase", name = "firebase-bom", version.ref = "firebaseBom" }
firebase-messaging = { group = "com.google.firebase", name = "firebase-messaging" }

# Utilities
gson = { group = "com.google.code.gson", name = "gson", version.ref = "gson" }
play-services-ads-identifier = { group = "com.google.android.gms", name = "play-services-ads-identifier", version.ref = "playServicesAdsIdentifier" }

Bước 2: Khai báo trong build.gradle.kts (Module: app)

Mở block dependencies và gọi các biến đã khai báo:

Kotlin

dependencies {
    // Mobio SDK (Local AAR)
    implementation(files("libs/mobio-sdk.aar"))

    // Dependencies từ Version Catalog
    implementation(libs.androidx.appcompat) // Đã có sẵn trong file của bạn
    implementation(libs.androidx.work.runtime.ktx)
    implementation(libs.gson)
    implementation(libs.play.services.ads.identifier)

    // Firebase Integration
    implementation(platform(libs.firebase.bom))
    implementation(libs.firebase.messaging)
}
Cách 2: Khai báo trực tiếp (Dành cho dự án cũ hoặc cần nhanh)

Sử dụng trực tiếp chuỗi ký tự trong file cấu hình.

Mở file build.gradle.kts (Module: app) và thêm đoạn mã sau:

Kotlin

dependencies {
    // Mobio SDK
    implementation(files("libs/mobio-sdk.aar"))

    // Core Android & WorkManager
    implementation("androidx.appcompat:appcompat:1.7.1")
    implementation("androidx.work:work-runtime-ktx:2.9.0") 

    // Firebase (Bắt buộc dùng platform() cho BOM trong Kotlin DSL)
    implementation(platform("com.google.firebase:firebase-bom:32.2.2"))
    implementation("com.google.firebase:firebase-messaging")

    // Utilities
    implementation("com.google.code.gson:gson:2.10.1")
    implementation("com.google.android.gms:play-services-ads-identifier:18.0.1")
}

2.3. Cấu hình Java Compatibility

SDK của Mobio yêu cầu Java phiên bản 8 trở lên. Hầu hết các dự án Android hiện đại đã đáp ứng yêu cầu này.

Hãy kiểm tra file `build.gradle` (module: app). Nếu `sourceCompatibility` và `targetCompatibility` đã được đặt thành `JavaVersion.VERSION_1_8` hoặc cao hơn (ví dụ: `JavaVersion.VERSION_11`), thì không cần thay đổi gì.

Nếu project chưa có cấu hình này hoặc đang dùng phiên bản thấp hơn, hãy thêm vào trong thẻ android:

android {
        // ...
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_1_8
            targetCompatibility JavaVersion.VERSION_1_8
        }
    }

Bước 3: Khai báo lớp Application trong AndroidManifest.xml

Mở file AndroidManifest.xml (app/src/main/AndroidManifest.xml) và thêm các quyền (permissions) và dịch vụ (services) cần thiết

Thêm Permissions

Đảm bảo các quyền sau đã được khai báo bên trong thẻ <manifest>. Nếu chưa có, vui lòng bổ sung:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Bắt buộc cho Android 13+ để hiển thị push notification -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Thêm Dịch vụ Firebase Messaging

Trường hợp 1: Dự án chưa tích hợp Firebase Messaging

Chưa có thông tin cho mục này.

Trường hợp 2: Dự án đã tích hợp Firebase Messaging

  • Bước 1: Mở file service extends từ FirebaseMessagingService để lắng nghe và xử lý dữ liệu từ Firebase, code thường có dạng
class MyFirebaseMessagingService : FirebaseMessagingService() {
    
}
  • Bước 2: Chuyển tiếp dữ liệu thông báo tới SDK
package com.mobio.mobiosdkkotlindemo

import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage
import com.mobio.sdk.Mobio

class MobioFirebaseMessagingService : FirebaseMessagingService() {

    companion object {
        private const val TAG = "FirebaseMsgService"
        private const val CHANNEL_ID = "mobio_notification_channel"
        private const val CHANNEL_NAME = "Mobio Notifications"
    }

    /**     * Được gọi khi nhận được message từ Firebase Cloud Messaging     */override fun onMessageReceived(remoteMessage: RemoteMessage) {
        super.onMessageReceived(remoteMessage)
        // Thêm hàm này để gửi thông tin tới Mobio SDK
        Mobio.getInstance().onMessageReceived(remoteMessage)

}

    
    /**     * Được gọi khi FCM token được refresh     * Token này cần được gửi lên server để có thể gửi notification đến thiết bị này     */override fun onNewToken(token: String) {
        super.onNewToken(token)
        Log.d(TAG, "Refreshed token: $token")
        
        // Thêm hàm này để gửi thông tin tới Mobio SDK
        Mobio.getInstance().setDeviceToken(token)
    }

}

Bước 4: Khởi tạo SDK

Cách tốt nhất để khởi tạo SDK là trong lớp Application. Điều này đảm bảo SDK được khởi chạy ngay khi ứng dụng bắt đầu.

Tạo một lớp kế thừa từ Application có tên MyApplication nằm cùng cấp với MainActivity

Java

import android.app.Application;
import com.mobio.sdk.Mobio;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Khởi tạo Mobio SDK
        Mobio.getInstance().initWithLaunchOptions(
            this,
            "YOUR_MERCHANT_ID",    // Thay bằng Merchant ID của bạn
            "YOUR_CONNECTOR_ID",   // Thay bằng Connector ID của bạn
            R.mipmap.ic_launcher , // Icon hiển thị trên notification
            "YOUR_API_URL",   // Thay bằng API URL của bạn  
            "SOURCE" // Thay bằng nguồn ghi nhận dữ liệu của bạn
        );
    }
}

Kotlin

package com.mobio.mobiosdkkotlindemo

import android.app.Application
import com.mobio.sdk.Mobio

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Khởi tạo Mobio SDK
        Mobio.getInstance().initWithLaunchOptions(
            this,
            "YOUR_MERCHANT_ID",    // Thay bằng Merchant ID của bạn
            "YOUR_CONNECTOR_ID",   // Thay bằng Connector ID của bạn
            R.mipmap.ic_launcher,  // Icon hiển thị trên notification
            "YOUR_API_URL",        // Thay bằng API URL của bạn
            "SOURCE"               // Thay bằng nguồn ghi nhận dữ liệu của bạn
        )
    }
}

Khai báo lớp Application trong AndroidManifest.xml

<application
    android:name=".MyApplication"
    ...
>
    <!-- ... -->
</application>

Lưu ý:

  • Thay thế thông tin MERCHANT_ID, CONNECTOR_ID, API_URL ở phần chuẩn bị.
  • Source (optional): thông tin phân loại nguồn dữ liệu khi Profile được ghi nhận trên hệ thống Mobio, giá trị mặc định là “App”

5. Quy tắc vận hành

  • Bắt buộc: Phải Sync Gradle thành công sau khi thêm các dependencies ở Bước 2. Nếu báo lỗi xung đột phiên bản (Version Conflict), vui lòng điều chỉnh các số version (ví dụ 18.5.0) sao cho tương thích với dự án hiện tại của bạn nhưng vẫn ưu tiên bản mới.
  • Tùy chọn: Nếu dự án không bật minifyEnabled true trong cấu hình Release, bạn có thể bỏ qua Bước 5 (Cấu hình Proguard).

6. Các câu hỏi thường gặp (FAQ)

Chưa có thông tin cho mục này.

7. Bước tiếp theo

Môi trường Android của bạn đã được cài đặt chính xác các thư viện cần thiết. Hãy chuyển sang bài tiếp theo để tiến hành gọi hàm:

  • [Kỹ thuật] Gọi hàm Khởi tạo SDK (INIT) trên ứng dụng Android


Những bài viết liên quan

Nội dung chính

Thắc mắc vẫn chưa được giải đáp?

Gửi email cho Đội ngũ CS ngay!

image-zoom
© MOBIO 2022 v1.2 Powered by MOBIO
Back to Top