Plugin

Firebase

Firebase Analytics, Crashlytics và Cloud Messaging (FCM). Firebase tự khởi động khi app mở — không có hàm init.

v1.0.0 Android iOS Autoload Firebase Addon leono_firebase

Gồm thư viện Android. Vẫn cần google-services.json của game — xem mục bên dưới. Giải nén vào thư mục gốc project Godot.

iOS chưa hỗ trợ

Trên iOS mọi hàm vẫn gọi được nhưng không làm gì; hàm async trả giá trị rỗng. Game không cần viết code riêng cho iOS.

Tạo Firebase cho game

Làm một lần khi gắn plugin vào mỗi game. File cấu hình thuộc về từng game, không nằm trong repo plugin.

Tạo projectVào Firebase Console → Add project, hoặc chọn project có sẵn của game.
Thêm app AndroidAdd app → Android. Android package name phải trùng Package → Unique Name trong export preset Android của Godot, ví dụ com.leono.mygame.
Tải google-services.jsonĐặt vào thư mục gốc project Godot: res://google-services.json. Muốn để chỗ khác thì sửa Project Settings → leono/firebase/google_services_json.
Bật dịch vụAnalytics (bật khi tạo project), Crashlytics (Build → Crashlytics → Enable), Cloud Messaging có sẵn.

Một file google-services.json có thể chứa nhiều app. Lúc export, plugin tự chọn app có package trùng với export preset; không trùng thì dùng app đầu tiên và báo cảnh báo.

Cài plugin

Buildbuild_android.bat firebase trong repo LeonoPlugins.
Copyplugins/firebase/addon/leono_firebase/ vào res://addons/.
Bật pluginProject Settings → Plugins → Leono Firebase. Autoload Firebase tự được thêm.
ExportInstall Android Build Template và bật Use Gradle Build như mọi plugin (xem Cài đặt nhanh).

Tự động thêm khi export
Thư viện	`firebase-analytics:23.2.0`, `firebase-crashlytics:20.1.1`, `firebase-messaging:25.1.3` (Firebase BoM 34.19.0)
Permission	`POST_NOTIFICATIONS` (Android 13+); `INTERNET`, `AD_ID` do Firebase thêm
Cấu hình	Giá trị từ `google-services.json`, service nhận tin FCM

Kiểm tra trên máy thật: Firebase.is_ready() phải trả true. Nếu false, xem log lúc export — plugin báo lỗi khi thiếu file hoặc sai package.

Bắt đầu

Firebase.log_event("level_complete", {"level": 3, "stars": 2, "boss": true})
Firebase.log_screen("shop")
Firebase.set_user_property("vip", "gold")

Firebase.crashlytics_set_user_id(player_id)
Firebase.crashlytics_log("Opened shop")
Firebase.crashlytics_set_key("coins", 1200)
Firebase.crashlytics_record_error("Purchase failed", {"sku": "gem_100", "code": 7})

func _ready() -> void:
    Firebase.token_refreshed.connect(_send_token_to_server)
    Firebase.notification_opened.connect(_open_from_notification)
    var launch := Firebase.get_launch_notification()
    if launch:
        _open_from_notification(launch)

func _after_tutorial() -> void:
    if Firebase.get_notification_permission() == "not_determined":
        await Firebase.request_notification_permission()
    _send_token_to_server(await Firebase.get_token())
    await Firebase.subscribe("news")

Cấu hình

Setting	Mặc định	Tác dụng
`leono/firebase/google_services_json`	`res://google-services.json`	Đường dẫn file cấu hình tải từ Firebase Console

API reference

is_ready() → boolAndroid

true khi Firebase đã khởi động trên máy thật. false trong editor/PC/iOS, hoặc khi export thiếu google-services.json.

Analytics

log_event(name: String, params := {}) → voidAndroid

Ghi sự kiện custom. Sai quy tắc tên thì Firebase bỏ qua sự kiện — autoload cảnh báo trong Output để phát hiện sớm.

Quy tắc	Giới hạn
Tên sự kiện	Chữ, số, `_`; bắt đầu bằng chữ; ≤ 40 ký tự; không dùng tiền tố `firebase_`, `google_`, `ga_`
Số params	≤ 25
Giá trị param	`String` (≤ 100 ký tự), `int`, `float`, `bool` (gửi dạng `"true"`/`"false"`)

Firebase.log_event("purchase_gem", {"sku": "gem_100", "price": 0.99, "first_time": true})

log_screen(screen_name: String, screen_class := "") → voidAndroid

Gọi tắt cho sự kiện screen_view.

set_user_id(id: String) → voidAndroid

ID người chơi trong hệ thống của game. "" để xoá. Không dùng email hay thông tin cá nhân.

set_user_property(name: String, value: String) → voidAndroid

Thuộc tính người dùng dùng để lọc báo cáo, ví dụ vip, country_group. Cần tạo custom definition trên Console mới xem được.

set_analytics_enabled(enabled: bool) → voidAndroid

Bật/tắt thu thập Analytics, ví dụ khi người chơi từ chối consent.

get_app_instance_id() → StringawaitAndroid

ID Analytics của lượt cài app này — dùng khi gửi sự kiện từ server (Measurement Protocol).

Crashlytics

crashlytics_log(message: String) → voidAndroid

Breadcrumb — lịch sử thao tác gửi kèm báo cáo crash/non-fatal tiếp theo. Ghi ở các điểm quan trọng: đổi màn, mua hàng, tải màn chơi.

crashlytics_set_key(key: String, value: Variant) → voidAndroid

Custom key gắn vào mọi báo cáo sau đó; giá trị String/int/float/bool giữ nguyên kiểu trên Console. Đặt nhiều key một lần: crashlytics_set_keys({"level": 3, "mode": "pvp"}).

crashlytics_set_user_id(id: String) → voidAndroid

Tìm báo cáo của một người chơi cụ thể trên Console.

crashlytics_record_error(message: String, data := {}) → voidAndroid

Ghi lỗi non-fatal — game không crash nhưng có gì đó sai. data chỉ gắn vào báo cáo này. Trên Console các lỗi này nằm dưới loại GodotError, nhóm theo nội dung message.

if not save_ok:
    Firebase.crashlytics_record_error("Save failed", {"slot": slot, "bytes": size})

crashlytics_set_enabled(enabled: bool) → voidAndroid

Bật/tắt gửi báo cáo.

crashlytics_test_crash() → voidAndroid

Làm crash app để kiểm tra báo cáo về tới Console. Báo cáo được gửi ở lần mở app tiếp theo.

Không để lời gọi này trong bản phát hành.

Cloud Messaging

get_token() → StringawaitAndroid

Token FCM của máy, "" nếu lỗi (thường do không có mạng hoặc Google Play Services). Gửi token lên server game để gửi thông báo riêng cho máy này.

delete_token() → boolawaitAndroid

Huỷ token hiện tại, ví dụ khi người chơi đăng xuất. Token mới được cấp lại qua token_refreshed nếu auto-init đang bật.

subscribe(topic: String) → boolawaitAndroid

Đăng ký topic để nhận thông báo gửi cho cả nhóm. Tên topic: chữ, số, -_.~%. Gọi song song nhiều topic được — mỗi lời gọi nhận đúng kết quả của nó.

await Firebase.subscribe("news")
await Firebase.subscribe("lang_" + NativeUtils.get_language())

unsubscribe(topic: String) → boolawaitAndroid

Huỷ đăng ký topic.

request_notification_permission() → boolawaitAndroid

Android 13+ hiện hộp thoại xin quyền thông báo. Android cũ hơn không có hộp thoại — trả về thông báo đang bật hay tắt.

Hệ thống chỉ cho hỏi lại rất ít lần. Hỏi sau khi người chơi đã thấy giá trị (ví dụ sau tutorial, hoặc khi bật nhắc năng lượng đầy), không hỏi ngay lúc mở app.

get_notification_permission() → StringAndroid

"granted" · "denied" · "not_determined" (Android 13+ chưa hỏi lần nào).

get_launch_notification() → DictionaryAndroid

Thông báo mà người chơi bấm để mở app (app chưa chạy): {message_id, from, data}. {} nếu mở app bình thường. data là phần custom data khi gửi tin.

set_messaging_auto_init(enabled: bool) → voidAndroid

false = không tạo token cho tới khi bật lại (ví dụ trước khi người chơi đồng ý điều khoản).

Signals

Signal	Khi nào
`token_refreshed(token: String)`	Token mới: lần đầu, cài lại app, xoá dữ liệu, sau `delete_token()`. Gửi lên server.
`message_received(message: Dictionary)`	Tin đến khi game đang mở, hoặc tin data-only khi game ở nền. `{message_id, from, title, body, data}`
`notification_opened(data: Dictionary)`	Người chơi bấm thông báo khi game đang chạy nền. `{message_id, from, data}`

Hướng dẫn: thông báo đẩy

Trạng thái game	Tin có `notification`	Tin chỉ có `data`
Đang mở	Không hiện thông báo — nhận qua `message_received`	`message_received`
Chạy nền	Hệ thống hiện thông báo; bấm vào → `notification_opened`	`message_received`
Đã tắt	Hệ thống hiện thông báo; bấm vào → `get_launch_notification()`	Không nhận được

Gửi thử: Firebase Console → Messaging → New campaign → Notifications → Send test message, dán token lấy từ get_token().

Hướng dẫn: kiểm tra Crashlytics

Gọi test crashThêm tạm một nút gọi Firebase.crashlytics_test_crash(), cài bản debug lên máy, bấm nút.
Mở lại appBáo cáo được gửi ở lần mở tiếp theo.
Xem ConsoleCrashlytics → báo cáo xuất hiện sau vài phút. Lần đầu có thể mất tới 30 phút.

Giới hạn hiện tại

Vấn đề	Chi tiết
iOS	Chưa hỗ trợ — mọi hàm không làm gì.
Phiên bản Firebase	BoM 34.19.0. BoM 35 build bằng Kotlin 2.4, Gradle build của Godot 4.7.2 (Kotlin 2.1) không đọc được → export lỗi.
Token FCM	Firebase Messaging 25.1 đánh dấu deprecated API token để chuyển sang Firebase Installation ID. Token vẫn chạy bình thường.
Stack trace Crashlytics	Chưa upload mapping file, phần Kotlin/Java có thể bị rút gọn.

Lịch sử phiên bản

Phiên bản	Thay đổi
`1.0.0`	Phát hành đầu tiên (Android): Analytics, Crashlytics, Cloud Messaging.