Gửi APK qua Zalo đủ dùng khi bạn có hai tester. Với ba tester trở lên và hai sprint song song, bạn không còn biết ai đang cầm build nào, build đó đã có bản vá nào, và lỗi được báo là lỗi của code hay của file APK cũ. Vấn đề không nằm ở công cụ: bạn thiếu một kênh phân phối có danh tính tester và số phiên bản.
Năm 2026 có ba kênh hợp lệ: Firebase App Distribution, Play internal testing và Play closed testing. Chúng không thay thế nhau. App Distribution tối ưu cho tốc độ và sự riêng tư của QA nội bộ; hai track Play kiểm tra đúng con đường mà người dùng thật sẽ đi qua.
Mục lục
Cập nhật 2026
- Target API 36: từ 31/08/2026, app mới và bản cập nhật trên Play phải target API 36, gia hạn tối đa đến 01/11/2026. App Distribution không kiểm tra điều này; chỉ track Play mới chặn.
firebase login:ciđã bị deprecate. CI dùng service account với Application Default Credentials (GOOGLE_APPLICATION_CREDENTIALS), không dùng refresh token.- Tester Android không cần UDID. Rào cản thật là file AAB: tester phải bật Play internal app sharing một lần.
- Không pin version Firebase trong bài. CLI, plugin và SDK phát hành liên tục; khai báo version ở một chỗ và lấy số từ release notes chính thức.
Ba kênh, ba mục đích khác nhau
| Kênh | Tester nhận build qua đâu | Phù hợp khi |
|---|---|---|
| Firebase App Distribution | Email mời, link cài APK, hoặc App Tester | QA hằng ngày, build theo PR, build chưa đưa vào Play |
| Play internal testing | Play Store qua opt-in link, tối đa 100 tester | Kiểm tra AAB, Play App Signing, luồng cập nhật thật |
| Play closed testing | Play Store, tối đa 2.000 email và Google Groups | Beta có kiểm soát, chuẩn bị production |
Điểm dễ hiểu sai nhất: App Distribution không phải store. Nó không review app, không có trang sản phẩm, không tự cập nhật trừ khi tester dùng App Tester, và link cài không tồn tại vĩnh viễn. Ngược lại, internal testing là track Play thật: build đi qua Play App Signing, chia APK theo cấu hình thiết bị, tester cập nhật như app Play bình thường. Đừng dùng internal testing để thay QA nhanh, cũng đừng dùng App Distribution để nghiệm thu bản phát hành.
Thiết lập Firebase App Distribution
Dự án và app
Tạo Firebase project, thêm một Android app với applicationId trùng package name trong app/build.gradle.kts. Sai một ký tự là App ID bạn dùng để phân phối không khớp app cài trên máy, và build vẫn upload thành công nhưng tester nhận một app khác định danh.
Để phân phối, bạn không cần thêm Firebase SDK và cũng không cần google-services.json. Hai thứ đó chỉ cần khi app dùng Auth, Firestore hay Crashlytics. App Distribution chỉ cần entry Android trong project và App ID dạng 1:1234567890:android:0a1b2c3d4e5f67890, lấy ở General settings. Nhiều hướng dẫn cũ làm bạn tưởng phải cài SDK trước.
Tester và nhóm
Tạo nhóm trước khi tạo build đầu tiên. Group alias là thứ CLI và Gradle tham chiếu, nên đặt alias ổn định (qa-noi-bo, beta) và chỉ đổi tên hiển thị. Alias đổi theo từng đợt sẽ khiến pipeline gửi build cho nhóm không tồn tại, trong khi lệnh vẫn trả về thành công.
firebase appdistribution:groups:create "QA nội bộ" qa-noi-bo
firebase appdistribution:testers:add "an@example.com" "binh@example.com" --group-alias qa-noi-bo
firebase appdistribution:groups:list
firebase appdistribution:testers:list
Với nhóm lớn, đừng gõ email trên dòng lệnh. Dùng --file khi thêm tester và --testers-file, --groups-file khi phân phối để danh sách nằm trong repo hoặc secret của CI.
Phân phối bằng Firebase CLI
npm install -g firebase-tools
firebase login
firebase projects:list
./gradlew :app:assembleRelease
firebase appdistribution:distribute \
app/build/outputs/apk/release/app-release.apk \
--app "1:1234567890:android:0a1b2c3d4e5f67890" \
--groups "qa-noi-bo" \
--release-notes-file "build/release-notes.txt"
--app là tham số bắt buộc và phải là App ID, không phải package name. --groups nhận alias cách nhau bằng dấu phẩy, --testers nhận email. Chọn một mô hình quản lý: theo nhóm hoặc theo danh sách email.
Với AAB, trỏ CLI vào file .aab. App Distribution nhận cả hai loại, nhưng tester Android phải bật internal app sharing trước khi cài bản AAB:
./gradlew :app:bundleRelease
firebase appdistribution:distribute \
app/build/outputs/bundle/release/app-release.aab \
--app "1:1234567890:android:0a1b2c3d4e5f67890" \
--groups "beta" \
--release-notes "RC1 sprint 42: sửa lỗi đăng nhập, thêm màn hình hoá đơn"
Sau khi upload, CLI in ra link cho tester và link tải binary có hạn một giờ; đừng đưa link tải trực tiếp cho người ngoài nhóm.
Gradle và CI
Plugin Gradle hữu ích khi muốn cấu hình phân phối nằm trong build variant thay vì trong pipeline. Khai báo plugin không kèm số version ở root, để version được giải quyết ở một chỗ duy nhất:
// build.gradle.kts (root)
plugins {
alias(libs.plugins.firebase.appdistribution) apply false
}
// app/build.gradle.kts
import com.google.firebase.appdistribution.gradle.firebaseAppDistribution
android {
buildTypes {
getByName("release") {
firebaseAppDistribution {
appId = "1:1234567890:android:0a1b2c3d4e5f67890"
artifactType = "APK"
groups = "qa-noi-bo"
releaseNotesFile = rootProject.file("build/release-notes.txt").path
}
}
}
}
Plugin lấy credential từ Firebase CLI nếu bạn đã firebase login. Trên CI không có phiên đăng nhập, nên dùng service account có role Firebase App Distribution Admin và trỏ GOOGLE_APPLICATION_CREDENTIALS vào file JSON. Task appDistributionUploadRelease không tự build — phải chạy assembleRelease trước.
#!/usr/bin/env bash
# ci/distribute.sh - chạy trong CI, không commit credential
set -euo pipefail
printf '%s' "$FIREBASE_SERVICE_ACCOUNT" > "$RUNNER_TEMP/firebase-sa.json"
export GOOGLE_APPLICATION_CREDENTIALS="$RUNNER_TEMP/firebase-sa.json"
./gradlew :app:assembleRelease
git log --pretty=format:"- %s (%h)" "$(git describe --tags --abbrev=0)..HEAD" > build/release-notes.txt
firebase appdistribution:distribute \
app/build/outputs/apk/release/app-release.apk \
--app "$FIREBASE_APP_ID" \
--groups "$FIREBASE_TESTER_GROUPS" \
--release-notes-file build/release-notes.txt \
--project "$FIREBASE_PROJECT_ID"
rm -f "$RUNNER_TEMP/firebase-sa.json"
--project đặt project đích tường minh. Trong CI nhiều môi trường, đây là cờ rẻ nhất để tránh đẩy build lên nhầm project. Fastlane là lựa chọn thay thế nếu team đã dùng nó cho iOS: plugin firebase_app_distribution bọc đúng lệnh trên.
bundle exec fastlane android distribute_beta
Versioning và release notes
versionCode là hợp đồng với hệ điều hành, không phải số trang trí. Android không cài đè APK có versionCode nhỏ hơn hoặc bằng bản đang cài; Play từ chối AAB trùng số. Quên tăng số, tester sẽ báo “vẫn lỗi cũ” trong khi build bạn vừa gửi chưa từng được cài.
Đừng sửa tay mỗi lần. Lấy số build từ CI và dành một dải riêng cho build thử:
// app/build.gradle.kts
val buildNumber = (providers.gradleProperty("buildNumber").orNull
?: providers.environmentVariable("BUILD_NUMBER").orNull
?: "0").toInt()
android {
defaultConfig {
versionCode = 10_000 + buildNumber // dải 10.000+ chỉ cho build nội bộ
versionName = "1.6.0-beta.$buildNumber"
}
}
Release notes phải viết cho tester: cái gì đã đổi, cần thử ở đâu, lỗi nào đã sửa. Danh sách commit thô đủ cho kỹ thuật nhưng vô nghĩa với QA. Nếu notes dài, dùng --release-notes-file để giữ định dạng và dễ review trong PR.
Tester nhận build bằng cách nào
Khi phân phối, Firebase gửi email cho tester mới và thông báo “build mới đã sẵn sàng” cho tester cũ. Lời mời có hạn 30 ngày và chỉ chấp nhận một lần; tester đăng nhập bằng bất kỳ tài khoản Google nào. Trên Android, tester mở link, chấp nhận lời mời, rồi cài APK trực tiếp hoặc qua Firebase App Tester, nơi gom các build được chia cho họ.
Không có bước đăng ký UDID trên Android. UDID là yêu cầu của phân phối ad hoc trên iOS: thiết bị phải vào provisioning profile và build phải ký lại. Nếu ai đó yêu cầu tester Android gửi UDID, họ đang bê checklist iOS sang. Rào cản tương đương của Android nằm ở hai chỗ: bật “install unknown apps” cho trình duyệt khi cài APK trực tiếp, và bật internal app sharing trong Play Store khi cài AAB (mở Play Store, vào Settings, tap số phiên bản bảy lần, rồi bật Internal app sharing).
Feedback có hai lớp: tester gửi báo cáo kèm ảnh chụp trong App Tester và Firebase gửi alert qua email; hoặc bạn dùng SDK App Distribution để hiện form ngay trong app. SDK này vẫn ở dạng beta và bản full có cơ chế tự cập nhật — thứ có thể bị coi là vi phạm chính sách Play nếu nằm trong bản lên store. Chỉ thêm SDK vào variant test.
Crash không tự xuất hiện: nếu build thử có Crashlytics và trỏ cùng Firebase project, crash vào dashboard như bản thường, kèm mapping file nếu upload đúng. Không có Crashlytics, tester chỉ còn cách mô tả đường dẫn tái hiện — lý do nên bật nó ngay từ build nội bộ đầu tiên.
Khi nào dùng kênh nào
| Tình huống | Kênh nên dùng | Lý do |
|---|---|---|
| Cần QA thử ngay sau merge, nhiều lần mỗi ngày | App Distribution | Không review, không cần Play Console, vài phút là xong |
| Cần kiểm tra AAB, Play App Signing, luồng cập nhật | Play internal testing | Đi đúng hạ tầng Play, giới hạn 100 tester |
| Beta cho người ngoài team, feedback có kiểm soát | Play closed testing | Tới 2.000 email, Google Groups, có review |
| Tài khoản cá nhân cần mở quyền production | Play closed testing | Track được Google tính cho yêu cầu testing |
Với tài khoản developer cá nhân tạo sau 13/11/2023, Google yêu cầu closed test với tối thiểu 12 tester opt-in liên tục ít nhất 14 ngày trước khi xin quyền production. Con số này từng thay đổi, nên kiểm tra lại trang “App testing requirements” trong Play Console trước khi cam kết deadline. Hệ quả thực tế: nếu chỉ dùng App Distribution, bạn không tích lũy được ngày nào cho yêu cầu này — thời gian test trên closed track phải bắt đầu sớm hơn bạn tưởng.
Tám lỗi thường gặp
1. Phân phối debug build
App Distribution không chặn build ký bằng debug key — tài liệu chỉ yêu cầu APK đã ký. Nhưng debug build bật debuggable, tắt R8, chạy chậm hơn và có hành vi khác bản release. Tester sẽ báo lỗi hiệu năng không tồn tại trong sản phẩm. Hãy build variant release đã ký, kể cả build nội bộ.
2. Quên tăng versionCode
Đây là lỗi im lặng nhất. Thêm bước kiểm tra trong CI: fail pipeline nếu versionCode không tăng so với lần phân phối trước. Đừng dựa vào việc tester gỡ app rồi cài lại.
3. Tester không nhận được gì
Lệnh thành công không có nghĩa là có người nhận. Kiểm tra ba thứ: alias nhóm tồn tại, email đã được thêm, và --project trỏ đúng Firebase project. Build đẩy lên project staging với nhóm của prod là combo thường gặp khi copy pipeline.
4. Secret nằm trong CI
Service account JSON commit vào repo hoặc base64 dán vào biến môi trường rồi in ra log là hai cách phổ biến để rò credential có role admin. Dùng secret store của CI, ghi file trong thư mục tạm, xóa sau khi chạy, và giới hạn role tối thiểu.
5. Coi App Distribution là store
Nó không thay thế Play. Link mời hết hạn, link tải binary hết hạn sau một giờ, không có cập nhật tự động cho người không dùng App Tester, và không có review policy giúp phát hiện vi phạm trước release. Đưa link này cho khách như bản chính thức là cách nhanh nhất để họ cài build không thể cập nhật.
6. Bỏ qua dữ liệu và quyền riêng tư
Build thử thường trỏ backend production, ghi log dữ liệu thật, và được cài trên máy cá nhân của người ngoài team. Trước khi mở rộng danh sách tester, chốt ba điểm: backend sandbox hay production, log có che dữ liệu cá nhân không, và tester đã biết họ đang chạy bản chưa hoàn thiện. Nếu app lên Play, data safety form và privacy policy vẫn phải đúng.
7. AAB mà không bật internal app sharing
Triệu chứng: tester bấm cài và nhận thông báo không thể cài. Nguyên nhân không phải quyền tài khoản mà là thiếu bật internal app sharing trên thiết bị test. Đây là thao tác một lần, nhưng phải nằm trong hướng dẫn onboarding tester thay vì để họ tự mò.
8. Quên target API khi chuyển sang track Play
App Distribution không quan tâm targetSdk. Internal và closed testing thì có: từ 31/08/2026 bản upload phải target API 36 (gia hạn đến 01/11/2026), nên build “chạy được trên máy tester” vẫn có thể bị Play chặn. Đặt compileSdk = 36 và targetSdk = 36 ngay từ đầu chu kỳ.
Nhìn tới 2027
Android 17 (API 37) vẫn ở dạng beta; đừng đưa nó vào kế hoạch như mốc đã chốt. Ở phía Firebase, App Testing agent (chạy test tự động trên thiết bị thật) đang được bổ sung vào cùng luồng phân phối, giảm phần smoke test thủ công. Nguyên tắc không đổi: kênh phân phối phải trả lời được “ai đang cầm build nào”.
Checklist trước khi giao build
- Build variant release, đã ký,
debuggabletắt,versionCodetăng so với lần trước. targetSdk = 36nếu build sẽ lên bất kỳ track Play nào.- Alias nhóm và
--projectđược kiểm tra trong pipeline, không hard-code trong script. - Release notes viết cho tester, không phải danh sách commit thô.
- Credential lấy từ secret store, ghi ra file tạm và xóa sau khi chạy.
- Hướng dẫn tester gồm: chấp nhận lời mời, bật internal app sharing nếu nhận AAB, cách gửi feedback và log.
Đọc tiếp trong chuỗi: tạo và ký APK/AAB để build đúng ngay từ đầu, danh sách kiểm tra xuất bản lên Play cho bước sau khi hết giai đoạn test, và Crashlytics cùng các thành phần Firebase để build thử có tín hiệu lỗi thay vì chỉ có báo cáo bằng lời. Toàn bộ thứ tự học nằm ở lộ trình Android.



