II. Falcon Analytics

Cung cấp công cụ để phân tích các chỉ số trong game, thông qua các hàm thống kê trong class DWHLog.

Hướng dẫn cơ bản sử dụng FalconAnalytic

Người sử dụng cần gọi các hàm tại các thời điểm nhất định trong game để gửi thông tin về server phân tích dữ liệu, sau đó có thể xem các dữ liệu đã được phân tích tại data4game.com.

Hướng dẫn xem số liệu chi tiết có tại https://falcon-game-studio.gitbook.io/falcon-bigdata/giai-thich-bieu-do/tong-quan

Hiện API đang cung cấp 8 hàm gọi thống kê là:

• LevelLog: thống kê các level trong game.

• ​InAppLog: thống kê chỉ số nạp của người chơi.

• AdsLog: thống kê chỉ số xem quảng cáo của người chơi.

• ResourceLog: thống kê các chỉ số tài nguyên mà người chơi nhận được trong game.

• SessionLog: thống kê khoảng thời gian chơi game của người chơi.

• FunnelLog: thống kê theo biểu đồ phễu, được thiết kế phân cấp người chơi theo 1 tính chất bất kỳ.

• PropretyLog : thống kê động các sự kiện/tính năng/vật phẩm người chơi đã mở khóa, được thiết kế để người chơi tự định nghĩa biểu đồ động thống kê tính năng bất kỳ.

• ActionLog: thống kê sự chuyển rời giữa 2 hành vi của người chơi, được thiết kế để truy vết thứ tự và phân tích hành vi người dùng.

Đồng thời có 2 log được thực hiện tự động là:

• RetentionLog: thống kê retention của người chơi.

• UserTotalTimeLog: thống kê tổng thời gian chơi game của người chơi mỗi lần chơi.

Chi tiết về các hàm log tự động trên có thể được xem tại Các hàm log tự động.

Chú ý:

• Các tham số trong các hàm , nếu không có ghi chú riêng, thì đều cần nhập giá trị khác null.

• strlen trong ghi chú(nếu có) là độ dài của giá trị string nhập vào.

• Nếu người chơi không có mạng internet khi chơi game, tức không thể gửi log lên server.

• Nếu SDK phiên bản 1.x.x, việc khởi tạo các giá trị nền cho FalconABTesting được thực hiện ở hàm Awake() của scene chứa Game Prefab Falcon ( trong FalconCore/Resources), vì vậy việc sử dụng trong scene đó chỉ nên được xử lý tại hàm Start() hoặc Update().

• Nếu SDK phiên bản 2.x.x, việc khởi tạo các giá trị nền cho FalconAnalytic được thực hiện kể từ khi gọi FalconMain.Init(), vì vậy cần kiểm tra giá trị FalconMain.InitComplete trước khi gọi.

if (FalconMain.InitComplete)
{
    //log something
}

• Trong trường hợp trò chơi tự ghi nhận được accountId và muốn đánh dấu việc một account_id sử dụng nhiều device khác nhau, SDK có cung cấp các hàm giúp người dùng tự khai báo account_id:

  • Nếu khai báo account_id trước khi khởi tạo SDK bằng FalconMain.Init() có thể sử dụng hàm FalconInfoUtils.AccountID(String accountId).

  • Nếu khai báo account_id sau khi gọi khởi tạo, ngoài việc sử dụng hàm FalconInfoUtils.AccountID(String accountId), người dùng cần phải gán thêm giá trị cho DWhMessage.Static.AccountId.

VD:

//Tại đây đảm bảo hệ thống chưa gọi FalconMain.Init()
    String account_id = GetAccountIDFromSomewhere();
    FalconInfoUtils.AccountID(accountId);
    FalconMain.Init();
    
    //......A few moments later.......
    
    //Tại đây có nhu cầu khai báo lại giá trị accountId
    String account_id = GetAccountIDFromSomewhere();
    FalconInfoUtils.AccountID = accountId;
    DwhMessage.Static.AccountId= accountId;
    //Không gọi FalconMain.Init() nữa do trước đó đã gọi khởi tạo rồi

Việc khai báo này chỉ cần thực hiện một lần. Nếu thành công, SDK sẽ tự ghi nhận giá trị và tự động điền trong các phiên tiếp theo.

1.1. Level log

Gọi mỗi khi người chơi kết thúc 1 level mới trong game.

Cấu trúc hàm gồm có:

void DWHLog.Log.LevelLog(int level, int duration, int wave, string difficulty, LevelStatus status)

• int level: level hiện đang chơi.

• int duration: thời gian người chơi sử dụng cho level (tính theo giây)

• int wave: số wave người chơi vượt qua (trước khi fail, hoặc tổng số wave của level, nếu người chơi pass).

• string difficulty: độ khó của level ("easy", "hard", "no hope", ...) (2 ≤ strlen ≤ 20)

• LevelStatus status: hiện trạng của level khi kết thúc (LevelStatus.pass - pass lần đầu, LevelStatus.fail - fail lần đầu)

hoặc:

void DWHLog.Log.LevelLog(int level, TimeSpan duration, int wave, string difficulty, LevelStatus status)

• int level: level hiện đang chơi.

• TimeSpan duration: thời gian người chơi sử dụng cho level.

• int wave: số wave người chơi vượt qua (trước khi fail, hoặc tổng số wave của level, nếu người chơi pass).

• string difficulty: độ khó của level ("easy", "hard", "no hope", ...) (2 ≤ strlen ≤ 20)

• LevelStatus status: hiện trạng của level khi kết thúc (LevelStatus.pass - pass lần đầu, LevelStatus.fail - fail lần đầu).

VD:

• DWHLog.Log.LevelLog(2, 103, 5, "normal", LevelStatus.pass)

• DWHLog.Log.LevelLog(50, 69, 0, "hard", LevelStatus.fail)

Logic cơ bản:

• Nếu người chơi đã từng vượt qua level đang chơi trước đây, log sẽ không được gửi lên (tức chỉ ghi nhận các trường hợp log với các level người chơi chưa từng vượt qua).

• Nếu chưa từng vượt level đang chơi, nếu :

  • LevelStatus == pass : Gửi log lên server và lưu lại giá trị level để xử lý trong tương lai.

  • LevelStatus == fail : Gửi log lên server.

Lưu ý:

• Level log chỉ được gửi về server nếu người chơi chưa từng vượt qua level, tức nếu người chơi đã vượt qua level x thì việc log chỉ được gửi khi level của log mới khác x.

• Một số phiên bản có để tên giá trị level thành maxPassedLevel, điều này sẽ được khắc phục tại các phiên bản sau.

1.2. InApp log

Gọi sau khi người chơi thực hiện InApp purchase trong game.

Cấu trúc hàm gồm có:

void DWHLog.Log.InappLog(int maxPassedLevel, string productId, string currencyCode, string price, string transactionId, string purchaseToken, string where)

• int maxPassedLevel: level tối đa mà người chơi đã vượt qua.

• string productId: id của gói nạp.

• string currencyCode: người chơi nạp thông qua đơn vị tiền tệ nào (Theo ISO 4217 currency codes, tức là "VND" thay vì "đ", "vnđ", "đồng", ...)

• string price: giá của gói nạp.

• string transactionId: id giao dịch.

• string purchaseToken: token mà google play trả về sau giao dịch, nếu không có sẽ để empty string ("").

• string where: địa điểm nạp (nạp trong shop/ ở gói pop up cuối level,...) (2 ≤ strlen ≤ 200)

VD:

• DWHLog.Log.InappLog(8, "pack_gem_20usd", "USD", "$30.99","GPA.330...528", "ffdhjgcgjamj ... CiSwg", "Level_45")

• DWHLog.Log.InappLog(15, "daily_pack_1", "KRW", "8400.00","GPA.335...779", "fcdfhoogaefl ... HMtQQ", "shop")

1.3. Advertisement log

Gọi sau khi người chơi hoàn thành xem ad trong game.

Cấu trúc hàm gồm có:

void DWHLog.Log.AdsLog(int maxPassedLevel, AdType type, string adWhere)

• int maxPassedLevel: level tối đa mà người chơi đã vượt qua

• AdType type: loại ad xem (AdType.interstitial, AdType.reward)

• string adWhere: địa điểm xem ad (xem trong shop, xem ở trong level để hồi sinh/ nhận phần thưởng,...) (2 ≤ strlen ≤ 50)

VD:

• DWHLog.Log.AdsLog(15, AdType.interstitial, "Video_RandomEndgame")

• DWHLog.Log.AdsLog(4, AdType.reward, "Video_Revival")

1.4. Resource log

Gọi mỗi khi người chơi nhận/sử dụng tài nguyên trong game.

Cấu trúc hàm gồm có:

void DWHLog.Log.ResourceLog(int maxPassedLevel, FlowType flowType, string itemType, string itemId, string currency, int amount)

• int maxPassedLevel: level tối đa mà người chơi đã vượt qua.

• FlowType flowType: người chơi nhận/sử dụng tài nguyên (FlowType.source - nhận, FlowType.sink - sử dụng).

• string itemType: nguồn cung cấp/tiêu thụ tài nguyên (khái quát) (2 ≤ strlen ≤ 20)

• string itemId: nguồn cung cấp/tiêu thụ tài nguyên (chi tiết) (2 ≤ strlen ≤ 50)

• string currency: loại tài nguyên người chơi nhận được (gem, gold, crystal, ...) (2 ≤ strlen ≤ 20)

• int amount: số lượng tài nguyên người chơi nhận được (amount > 0)

VD:

• DWHLog.Log.ResourceLog(13, FlowType.source, "login", "login","gem", 2)

• DWHLog.Log.ResourceLog(5, FlowType.sink, "upgrade", "upgrade_weapon","gold", 4185)

Chú thích: itemId có thể coi như là subType cho itemType, chú thích chi tiết hơn cho nguồn tài nguyên (ví dụ như cùng là upgrade trong itemType, nhưng itemId sẽ chi tiết hơn như upgradeweapon/ upgradecharacter/ ...), mục đích để tiện cho việc vẽ biểu đồ phân tích.

1.5. Session log

Gọi mỗi khi kết thúc đo khoảng thời gian người chơi sử dụng cho một tính năng (event, ...)

Cấu trúc hàm gồm có:

void DWHLog.Log.SessionLog(int maxPassedLevel, int sessionTime, string gameMod)

• int maxPassedLevel: level tối đa mà người chơi đã vượt qua.

• int sessionTime: tổng thời gian người chơi sử dụng cho chức năng (tính theo giây, 5 ≤ sessionTime ≤ 172800)

• string gameMod: tên chức năng.

hoặc:

void DWHLog.Log.SessionLog(int sessionTime, string gameMod)

• int sesionTime: tổng thời gian người chơi sử dụng cho chức năng (tính theo giây, 5 ≤ sessionTime ≤ 172800)

• string gameMod: tên chức năng.

Việc sử dụng biến maxPassedLevel tùy thuộc việc đánh giá kết quả phân tích có phụ thuộc level người chơi hay không.

hoặc:

void DWHLog.Log.SessionLog(int maxPassedLevel, TimeSpan sessionTime, string gameMod)

• int maxPassedLevel: level tối đa mà người chơi đã vượt qua.

• TimeSpan sessionTime: tổng thời gian người chơi sử dụng cho chức năng (5 secs ≤ sessionTime ≤ 2 days)

• string gameMod: tên chức năng.

hoặc:

void DWHLog.Log.SessionLog(TimeSpan sessionTime, string gameMod)

• TimeSpan sesionTime: tổng thời gian người chơi sử dụng cho chức năng (5 secs ≤ sessionTime ≤ 2 days)

• string gameMod: tên chức năng.

Việc sử dụng biến maxPassedLevel tùy thuộc việc đánh giá kết quả phân tích có phụ thuộc level người chơi hay không.

VD:

• DWHLog.Log.SessionLog(10, 1864, "event_christmas_day1_2021")

• DWHLog.Log.SessionLog(4063, "daily_gameplay")

1.6. FunnelLog

Là log sử dụng để vẽ biểu đồ phễu, trong đó tạo ra các mức chặn và lọc người chơi cho thấy tỷ lệ phần trăm người chơi qua từng mức.

Cấu trúc hàm gồm có :

public DwhFunnelLog(int maxPassedLevel, string funnelName, string action, int priority)

• int maxPassedLevel: level hiện tại của người chơi.

• string funnelName: tên của biểu đồ phễu (2 ≤ strlen ≤ 200)

• string action: tên của mức chặn (2 ≤ strlen ≤ 200)

• int priority: thứ tự của mức chặn trong biểu đồ (đếm từ 0)

VD:

• DWHLog.Log.DwhFunnelLog(20, "inapp_purchase", "whale", 17)

• DWHLog.Log.DwhFunnelLog(5, "story_line", "chapter_7", 53)

Logic cơ bản:

• Nếu priority lớn hơn 0, và chưa từng log của priority trước đó với cùng funnelName (như priority đang log là 5 với funnelName là "level" nhưng hệ thống ghi nhận chưa từng log với priority 4 với funnelName là "level") -> log không đúng trình tự -> không gửi log lên -> việc gửi log cần được thực hiện theo đúng trình tự priority 0 -> 1 -> 2 -> 3 -> ...

• Nếu hệ thống ghi nhận đã từng log priority hiện tại trước đó với cùng funnelName (hiện log funnelName là "level", priority là 4 nhưng trong quá khứ cũng từng log funnelName là "level", priority là 4) thì việc log hiện tại sẽ bị đánh giá là trùng lặp và không được gửi lên.

Lưu ý: Theo đúng tính chất của biểu đồ phễu, người chơi phải qua lần lượt từng mức chặn theo thứ tự tăng dần, nên việc log của người chơi cũng phải được thực hiện lần lượt, log sẽ không được gửi đi nếu việc log có thứ tự không đúng, ví dụ nếu người chơi đã log funnel "play_date" với các priority 0 -> 1 -> 2 -> 3 ( tức hiện đang ở mức 3), thì tiếp theo người chơi sẽ phải log funnel "play_date" ở priority 4 chứ không thể ở các mức khác như 5, 9, 2, ...

1.7. Property log

Gọi mỗi khi người chơi mở khóa 1 tính năng, vật phẩm, sự kiện,... Đây là log được thiết kế giúp người sử dụng có thể tự định nghĩa động giá trị muốn tổng hợp.

Cấu trúc hàm gồm có:

void DWHLog.Log.PropertyLog(int maxPassedLevel, string name, string value, int priority)

• int maxPassedLevel: level tối đa mà người chơi đã vượt qua.

• string name: tên loại tính năng/ vật phẩm mở khóa (2 ≤ strlen ≤ 50)

• string value: loại tính năng/ vật phẩm mở khóa (2 ≤ strlen ≤ 50)

• int priority: Phân cấp bậc, thứ tự của property, được server dùng để sắp xếp và lên biểu đồ.

VD:

• DWHLog.Log.PropertyLog(99, "weapon", "holy_moly_whack_a_moley_legendary_cannon", 99999)

• DWHLog.Log.PropertyLog(69, "level", "super_secret_hidden_level",5)

• DWHLog.Log.PropertyLog(96, "mission", "extremly_difficult_mission_that_nobody_can_complete",18)

1.8. Action log

Gọi khi mà người chơi vừa chuyển đổi giữa hai hành động/sự kiện/scene/panel/v.v. Đây là một loại log được thiết kế để truy vết thứ tự và phân tích hành vi của người dùng.

Cấu trúc hàm gồm có:

void DWHLog.Log.ActionLog(string from, string to, int time, int priority)

• string from: hành động trước đó của người chơi (2 ≤ strlen ≤ 50)

• string to: hành động hiện tại của người chơi (2 ≤ strlen ≤ 50)

• int time: thời gian người chơi dành cho hành động trước đó trước khi chuyển đổi (tính theo giây)

• int priority: Phân cấp bậc, thứ tự của action (để server phân tích và lên biểu đồ).

hoặc:

void DWHLog.Log.ActionLog(string from, string to, TimeSpan time, int priority)

• string from: hành động trước đó của người chơi.

• string to: hành động hiện tại của người chơi.

• TimeSpan time: thời gian người chơi dành cho hành động trước đó trước khi chuyển đổi.

• int priority: phân cấp bậc, thứ tự của action (để server phân tích và lên biểu đồ).

VD:

• DWHLog.Log.ActionLog("shop", "homescene", 965, 12)

• DWHLog.Log.ActionLog("weapon_upgrade_scene", "play_level", 30, 1)

• DWHLog.Log.ActionLog("minigame_select_panel", "đạp_zịt_game",985, 5)