Trang chủ › Hướng dẫn › Tích hợp Android

Tích hợp thư viện vào ứng dụng Android

Chỉ cần một dependency và một dòng khởi tạo, log của ứng dụng bạn đang phát triển sẽ được gửi về trang công cụ theo thời gian thực. Trang này dành cho lập trình viên Android.

Thư viện hoạt động như thế nào?

HVTD-9803 LogCat gồm ba phần:

• Thư viện hvtd9803-logcat – bạn thêm vào ứng dụng của mình. Thư viện đọc logcat của chính tiến trình ứng dụng, mã hóa từng dòng bằng AES-256-GCM rồi chuyển cho app Listener qua AIDL.
• App HVTD-9803 Listener – cài từ Google Play trên cùng thiết bị. Listener hiển thị Public Key, nhận Mã Authen và gửi log đã mã hóa lên máy chủ qua WebSocket bảo mật.
• Trang công cụ – nơi bạn tạo phiên và xem log trên trình duyệt.

Vì thư viện đọc log bằng lệnh logcat --pid của tiến trình hiện tại, mọi log ứng dụng ghi qua android.util.Log hoặc Timber đều được thu, bạn không cần đổi cách ghi log trong code.

Yêu cầu

Bước 1: Khai báo Maven Central

Hầu hết dự án Android đã có sẵn. Nếu chưa, thêm vào settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

Bước 2: Thêm dependency

Thư viện chỉ nên chạy trong bản debug/QA. Có hai cách, chọn một.

Cách A (khuyến nghị): chỉ đóng gói vào bản debug

Bản release hoàn toàn không chứa thư viện. Trong app/build.gradle.kts:

dependencies {
    debugImplementation("com.aigoox.library:hvtd9803-logcat:2.1")
}

Vì lớp của thư viện không tồn tại trong bản release, phần khởi tạo phải đặt trong source set riêng cho từng build type. Tạo hai tệp cùng tên, cùng package:

app/src/debug/java/com/example/app/LogcatBridge.kt

package com.example.app

import android.app.Application
import com.aigoox.hvtd9803_logcat.HVTD9803Controller

object LogcatBridge {
    fun init(app: Application) {
        HVTD9803Controller(isDebug = true, context = app).initialize()
    }
}

app/src/release/java/com/example/app/LogcatBridge.kt

package com.example.app

import android.app.Application

object LogcatBridge {
    fun init(app: Application) = Unit
}

Nếu dự án có thêm build type khác (ví dụ staging), tạo tệp tương ứng trong src/staging/ và chọn stagingImplementation nếu muốn bật log cho bản đó.

Cách B: đóng gói mọi bản, chỉ kích hoạt ở debug

Đơn giản hơn nhưng mã thư viện vẫn nằm trong APK/AAB release (ở trạng thái không hoạt động):

dependencies {
    implementation("com.aigoox.library:hvtd9803-logcat:2.1")
}

Khi đó luôn truyền isDebug = BuildConfig.DEBUG ở bước khởi tạo. Với Android Gradle Plugin 8 trở lên, nhớ bật lớp BuildConfig:

android {
    buildFeatures {
        buildConfig = true
    }
}

Dự án dùng Groovy thì viết debugImplementation 'com.aigoox.library:hvtd9803-logcat:2.1' và buildFeatures { buildConfig true }.

Bước 3: Khởi tạo trong Application

Gọi khởi tạo trong onCreate() của lớp Application, ngay sau super.onCreate():

class RootApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        LogcatBridge.init(this)            // Cách A
        // Cách B:
        // HVTD9803Controller(isDebug = BuildConfig.DEBUG, context = this).initialize()
    }
}

Nếu dự án chưa có lớp Application, khai báo lớp mới trong AndroidManifest.xml:

<application
    android:name=".RootApplication"
    ... >

Đã có lớp Application thì chỉ thêm dòng khởi tạo vào onCreate() hiện có, không tạo lớp thứ hai.

Bước 4: Build và bàn giao cho QA

1. Sync Gradle và build biến thể debug.
2. Trên thiết bị kiểm thử, cài HVTD-9803 Listener từ Google Play trước.
3. Cài APK debug của ứng dụng bạn.
4. Gửi QA đường dẫn Hướng dẫn sử dụng để thực hiện các bước xác thực.

Những gì thư viện thêm vào ứng dụng

Khi khởi tạo, thư viện:

• Gọi Timber.plant(Timber.DebugTree()). Nếu ứng dụng của bạn cũng tự plant một DebugTree, log Timber có thể bị in hai lần trong bản debug.
• Tạo cặp khóa RSA-2048 trong bộ nhớ và kết nối tới dịch vụ của Listener (thử lại tối đa 5 lần, mỗi lần cách 1 giây nếu Listener chưa sẵn sàng).
• Chỉ bắt đầu đọc và gửi log sau khi QA xác thực thành công trong Listener; dừng khi QA bấm “Đóng kết nối”.
• Bỏ qua log của chính thư viện (tag HVT9803Logcat) để không tạo vòng lặp.

Manifest của thư viện được gộp vào ứng dụng với các khai báo:

<uses-permission android:name="com.aigoox.hvtd9803.LOG_SERVICE" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<queries>
    <package android:name="com.aigoox.hvtd9803" />
</queries>

Khối <queries> (có từ bản 2.1) cần để Android 11 trở lên cho phép kết nối tới Listener, vì vậy hãy dùng bản 2.1. Với cách A, các khai báo này chỉ có trong bản debug. Nếu không muốn quyền SYSTEM_ALERT_WINDOW xuất hiện, có thể gỡ bằng manifest merger:

<uses-permission
    android:name="android.permission.SYSTEM_ALERT_WINDOW"
    tools:node="remove" />

Ứng dụng nhiều tiến trình

Thư viện chỉ đọc log của tiến trình nơi nó được khởi tạo. Nếu ứng dụng có service chạy ở tiến trình riêng (android:process), lớp Application sẽ chạy lại trong tiến trình đó; hãy chắc chắn bạn khởi tạo ở đúng tiến trình đang ghi log cần theo dõi.

Kiểm tra nhanh

• Ứng dụng là bản debug và LogcatBridge.init (hoặc HVTD9803Controller) được gọi trong Application.onCreate().
• Listener được cài trước ứng dụng; sau khi mở ứng dụng một lần, ứng dụng xuất hiện trong danh sách của Listener.
• Thêm một dòng Log.d("Smoke", "hello") khi bấm một nút để kiểm tra log đến được trang công cụ.

Xử lý sự cố

Lưu ý bảo mật

Chỉ bật thư viện cho bản debug/QA. Không ghi mật khẩu, token hay dữ liệu cá nhân vào log, vì người xem phiên sẽ đọc được toàn bộ nội dung log. Xem thêm Bảo vệ log khi truyền qua mạng và Chính sách bảo mật.

Tiếp theo: luồng sử dụng từng bước cho QA và Dev.