search

Adjust Plugin

Dùng để tự động đẩy 1 số thông tin của Adjust lên GSM, và các Event tự động gửi lên Adjust

hashtag
Tài liệu sử dụng Adjust Plugin

hashtag
1. Tổng quan

Adjust Plugin (CSCMobi) tích hợp Adjust SDK để tracking attribution, sự kiện (event) và ad revenue. Plugin gồm:

  • GSMAdjustInfo: Component chính — nhận config từ GSMCore, khởi tạo Adjust SDK (Start Manually), gửi event theo mapping từ file p-tracking.json, và lắng nghe level/ad impression/retention để tự gửi event lên Adjust.

  • Prefab GSMAdjustInfo: Prefab chứa component GSMAdjustInfo, cần đặt trong Scene đầu tiên (xem mục 2).

  • Adjust SDK Prefab: Prefab gốc của Adjust (Assets/Adjust/Prefab/Adjust.prefab), cũng phải có trong Scene đầu tiên và cấu hình Start SDK Manually (xem mục 2 và 4).

Tích hợp với GSM: môi trường (Sandbox/Production) lấy từ GSMCore config; session parameters (appId, deviceId, userId...) được thêm khi có config / login.

hashtag
2. Lưu ý quan trọng: Prefabs phải ở Scene đầu tiên

Bắt buộc: Cả hai Prefab sau phải được đặt trong Scene đầu tiên (Bootstrap / scene load đầu tiên khi chạy game):

Prefab
Đường dẫn
Lý do

Adjust

Assets/Adjust/Prefab/Adjust.prefab

Adjust SDK cần tồn tại từ lúc app khởi động; GSMAdjustInfo dùng FindObjectOfType<Adjust>() để lấy component và khởi tạo SDK. Nếu scene đầu không có Adjust, khi GSMCore gửi config có thể không tìm thấy Adjust → lỗi.

GSMAdjustInfo

Assets/CSCMobiPlugin/AdjustPlugin/Prefabs/GSMAdjustInfo.prefab

Component đăng ký GSMCore.OnGetConfig trong Awake và khởi tạo Adjust khi nhận config. Cần có mặt từ scene đầu để nhận config sớm và gọi Adjust.start().

Hậu quả nếu không đặt ở scene đầu:

  • Adjust SDK có thể không được start (hoặc start sai thời điểm).

  • GSMAdjustInfo có thể không tìm thấy Adjust → log lỗi "Can't FindObjectOfType()!" và không gửi event.

  • Attribution và event tracking có thể mất hoặc sai.

Cách làm: Mở Scene đầu tiên (ví dụ Bootstrap.unity), kéo thả cả hai Prefab vào Hierarchy (hoặc giữ instance đã có). Không cần đặt lại ở các scene khác; GSMAdjustInfo và Adjust đều dùng DontDestroyOnLoad nên tồn tại xuyên suốt app.

hashtag
3. Cấu trúc thư mục Adjust Plugin

  • Resources/p-tracking.json: Load bằng Resources.Load<TextAsset>("p-tracking"). File phải nằm trong một thư mục tên Resources (ở đây là AdjustPlugin/Resources). Nếu copy/move file, đảm bảo vẫn nằm trong Resources và tên resource là "p-tracking" (không cần ghi đuôi .json).

hashtag
4. Cấu hình Adjust Prefab (Scene đầu tiên)

Prefab Adjust (Assets/Adjust/Prefab/Adjust.prefab) cần:

  1. Start SDK Manually = true GSMAdjustInfo sẽ gọi Adjust.start(adjustConfig) sau khi nhận GSMCore config. Nếu để Start Manually = false, SDK sẽ tự start và có thể conflict hoặc thiếu session parameters.

  2. App Token Điền App Token của app trong dashboard Adjust. Nếu để trống, GSMAdjustInfo sẽ log lỗi "Adjust AppToken is Empty!" và không start SDK.

Các option khác trên Adjust prefab (environment, log level, v.v.) có thể để mặc định; GSMAdjustInfo tạo AdjustConfig riêng và set environment theo GSMCore (Development → Sandbox, Production → Production).

hashtag
5. Luồng hoạt động

  1. Scene đầu load Cả Adjust prefab và GSMAdjustInfo prefab đều có trong scene. GSMAdjustInfo.Awake():

    • Đăng ký GSMCore.OnGetConfig, GSMCore.OnLoginSuccess

    • DontDestroyOnLoad(gameObject)

    • Load p-tracking.json vào dictionary eventName → eventToken

    • Load danh sách event đã gửi (one-time events) từ PlayerPrefs

  2. Khi GSMCore gửi config (OnGetConfig):

    • Chọn môi trường Adjust: Development → Sandbox, Production → Production (Editor luôn Development).

    • SetAdjustInfo(): FindObjectOfType<Adjust>(), lưu reference, set App Token/environment lên GSMCore, đăng ký Adjust.getAdid với GSMCore.

    • Thêm session callback parameters: appId, deviceId, appVersion, os.

    • InitAdjustSdk(environment): tạo AdjustConfig, set attribution/event success/event failure delegate, gọi Adjust.start(adjustConfig).

  3. Sau khi login (OnLoginSuccess):

    • Thêm session parameter userId.

    • Tính retention (số ngày từ install đến hiện tại); nếu có event tương ứng trong p-tracking (ví dụ Day1_retention, Day7_retention) và chưa gửi, sẽ gửi event đó một lần.

  4. Event tự động (khi có sự kiện tương ứng):

    • Level start: GSMAnalytics.OnMainLevelLog với status = start → tìm key Start_level_{currentLevel} trong p-tracking, gửi event token tương ứng (chỉ gửi một lần mỗi token).

      • Nguyên tắc mapping: Game truyền currentLevel (số ngày hoặc level hiện tại) khi gọi LevelLog → JSON phải có key tương ứng theo cấu trúc Start_level_{currentLevel}.

      • Ví dụ: Nếu game gọi LevelLog(currentLevel = 5), JSON cần có "eventName": "Start_level_5" để map sang token Adjust.

      • Lưu ý: Tên key trong JSON phải khớp chính xác với giá trị currentLevel được truyền từ code (case-sensitive, không có khoảng trắng thừa).

    • Ad impression: GSMAnalytics.OnAdimpressionLog (level, adType) → gửi event theo loại ad (Reward, Interstitial, Banner) và các rule: mỗi impression, lần thứ N (Show_adfull_N / Show_reward_N), lần đầu trong ngày (Impression_day), v.v.

    • Retention: Khi login, gửi event DayX_retention tương ứng số ngày retention (nếu có trong p-tracking và chưa gửi).

Tất cả event “chỉ gửi một lần” được lưu trong PlayerPrefs (gsm_adjust_send) để không gửi trùng.

hashtag
6. File p-tracking.json

File định nghĩa mapping eventName → eventToken (event token lấy từ Adjust dashboard).

Vị trí: AdjustPlugin/Resources/p-tracking.json (load với Resources.Load<TextAsset>("p-tracking")).

Cấu trúc: Mảng JSON, mỗi phần tử có hai field:

Ví dụ:

  • Start_level_1 → token cho event “bắt đầu level 1”.

  • Show_adfull_5 → token cho event “xem interstitial lần thứ 5”.

  • Reward_impression → mỗi lần có reward impression sẽ gửi event này.

  • Day3_retention → gửi khi user login và đúng ngày thứ 3 sau install.

Lưu ý:

  • eventName không được trùng nhau; nếu trùng, script sẽ log lỗi và không load mapping.

  • eventToken phải điền đúng token tạo trên Adjust dashboard; để trống thì event không có giá trị trên Adjust.

  • Có thể thêm/bớt dòng theo nhu cầu tracking; chỉ cần giữ đúng format và không trùng eventName.

Các key đang được dùng trong code (tham khảo):

  • Level: Start_level_1 … Start_level_30 (và có thể mở rộng).

  • Interstitial: Inter_impression, Show_adfull_5, Show_adfull_10, Show_adfull_20, Interstitial_Impression_day.

  • Reward: Reward_impression, Show_reward_1, Show_reward_5, Show_reward_10, Show_reward_20, Reward_Impression_day.

  • Banner: Banner_impression, Banner_Impression_day.

  • Retention: Day1_retention … Day7_retention, Day14_retention, Day20_retention, Day30_retention.

  • IAP: First_IAP (có thể dùng từ chỗ khác).

hashtag
7. Gửi event tùy chỉnh từ code (AdjustController)

Ngoài event tự động từ GSMAdjustInfo, game có thể gửi event trực tiếp qua Adjust:

  • Dùng AdjustController (Assets/Scripts/Plugin/AdjustController.cs): có [RequireComponent(typeof(Adjust))], gắn cùng GameObject với Adjust. Trong đó có thể gọi:

    • AdjustEvent adjustEvent = new AdjustEvent(eventToken);

    • adjustEvent.addCallbackParameter("key", "value"); (nếu cần)

    • Adjust.trackEvent(adjustEvent);

Hoặc bất kỳ script nào (sau khi Adjust đã start):

Event token lấy từ Adjust dashboard. Nếu muốn event chỉ gửi một lần, cần tự lưu trạng thái (PlayerPrefs hoặc server).

hashtag
8. Tích hợp Ad Revenue (AdjustImpressionTracking)

Module LogImpression có AdjustImpressionTracking: khi ghi nhận ad revenue (MAX, AdMob, v.v.), có thể gửi lên Adjust qua Adjust.trackAdRevenue(adjustAdRevenue).

  • Tạo AdjustAdRevenue với source tương ứng (ví dụ AdjustConfig.AdjustAdRevenueSourceAppLovinMAX).

  • Set revenue, currency, network, unit, placement (tùy chọn).

  • Gọi Adjust.trackAdRevenue(adjustAdRevenue).

Điều này thường được gọi từ layer tracking chung (ví dụ MAX/AdMob impression callback), không cần cấu hình gì thêm trong Adjust Plugin ngoài việc đảm bảo Adjust đã start và Prefabs ở scene đầu.

hashtag
9. Checklist triển khai

  1. Scene đầu tiên

    • Có prefab Adjust (Assets/Adjust/Prefab/Adjust.prefab).

    • Có prefab GSMAdjustInfo (Assets/CSCMobiPlugin/AdjustPlugin/Prefabs/GSMAdjustInfo.prefab).

  2. Adjust prefab

    • Start SDK Manually = true.

    • App Token đã điền.

  3. GSMCore

    • Đảm bảo app có gọi/config GSMCore để sự kiện OnGetConfig (và khi cần OnLoginSuccess) được phát.

  4. p-tracking.json

    • Nằm trong AdjustPlugin/Resources/, tên resource p-tracking.

    • Điền đủ eventToken cho các eventName cần dùng; không trùng eventName.

  5. Event level / ad

    • Game gọi đúng API GSM (ví dụ level start, ad impression) để GSMAdjustInfo nhận và map sang event Adjust theo p-tracking.json.

Khi đó Adjust Plugin sẽ khởi tạo đúng từ scene đầu, nhận config và login từ GSMCore, và gửi event/attribution/ad revenue theo cấu hình.

PreviousCSCPluginNextLog Impression

Last updated