1. Các hàm Log cơ bản
Doc cho Analytic 3.x.x
Last updated
Doc cho Analytic 3.x.x
Last updated
Hãy nhớ thêm game của bạn trên data4game. Nếu thiếu bước này, các dữ liệu sẽ không được ghi nhận trên dashboard. Xem thêm hướng dẫn tại .
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 .
Hướng dẫn xem số liệu chi tiết có tại
Hiện API đang cung cấp 8 hàm gọi thống kê là:
Đồ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.
Chú ý:
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 thì SDK sẽ tự động lưu lại log để gửi vào các phiên sau. Tuy nhiên, để đảm bảo tối ưu, SDK chỉ lưu tối đa 100 log gần nhất chưa gửi.
Nếu bạn cần thay đổi một trường dữ liệu thống kê cụ thể, bạn có thể tham khảo FPlayerInfoRepo.
Kể từ phiên bản 2.2.2, chúng tôi không còn loại bỏ các log lỗi mà sẽ cố gắng đưa giá trị về đúng format. Điều này được thực hiện nhằm không bỏ qua bất kỳ 1 event nào của player, giúp đảm bảo tính đẩy đủ của dữ liệu. Tuy nhiên, khi sử dụng các phiên bản này, người dùng phải tự đảm bảo logic của LevelLog và FunnelLog.
Gọi mỗi khi người chơi bắt đầu/kết thúc 1 level mới trong game. Sau khi tạo bản ghi cần gọi hàm Send() để gửi bản tin đi ( new FLevelLog(...).Send(); )
Constructor của bản ghi:
int currentLevel: level hiện đang chơi.
string difficulty(!= null): độ khó của level ("easy", "hard", "no hope", ...; nếu game không có độ khó, hãy nhập "default")
LevelStatus status: hiện trạng của level khi kết thúc
LevelStatus.Start(từ phiên bản Analytic 3.1.9)- bắt đầu chơi level ( mỗi lần người chơi chơi level đều log lên, không chỉ log 1 lần duy nhất)
LevelStatus.Pass - pass lần đầu
LevelStatus.Fail - chơi level fail trong khi chưa pass level lần nào
LevelStatus.ReplayPass - đã qua level từ trước, giờ chơi lại và vẫn qua level
LevelStatus.ReplayFail - đã qua level từ trước, giờ chơi lại và fail level
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 (mặc định là 0, tức không cần truyền vào nếu không quan tâm, hoặc level của game không có wave)
VD:
new FLevelLog(2, "normal", LevelStatus.pass, TimeSpan.FromSeconds(69), 5).Send()
new FLevelLog(50, "hard", LevelStatus.fail, TimeSpan.FromMinutes(6), 9).Send()
Logic cơ bản:
Sẽ có các trạng thái chơi: Pass, Fail, RePlayPass, RePlayFail
Nếu người chơi chưa Pass lần đầu thì Fail bao nhiêu lần cũng gửi lên.
Khi người chơi Pass lần đầu thì gửi lên là Pass
Nếu người chơi Pass lần đầu chơi lại bị Fail sẽ gửi lên là RePlayFail.
Khi người chơi đã Pass lần đầu chơi lại Pass sẽ gửi lên là RePlayPass.
VD: Người chơi A chơi level 5 lần thứ 10 thì pass. Pass xong người chơi đó chơi lại level 5 thêm 3 lần nữa, trong 3 lần chơi có 2 lần pass, 1 lần fail thì dữ liệu sẽ được log như sau: người chơi A có 9 LOG lượt chơi fail ở level 5, 1 LOG pass ở level 5, 2 LOG replaypass ở level 5 và 1 LOG repplayfail ở level 5.
Lưu ý:
Ngoài status Start, không nhất thiết phải quan tâm tới status ReplayPass và ReplayFail, chỉ cần nhập status Pass/Fail và SDK sẽ chuyển sang status tương ứng( tức trong code chỉ cần gọi 3 status là Start/Pass/Fail)
1 Level sẽ được đánh giá độ độc nhất bằng giá trị LevelId, mặc định là currentLevel + "Difficulty" + difficulty. Nếu game của bạn đánh giá level theo cách khác, xin hãy override hàm này.
Giá trị level từ level log ( nếu status=Pass) sẽ được lưu lại và sử dụng để update giá trị maxPassedLevel (level tối đã người chơi đã vượt qua).
Nếu chỉ log level từ level 1 thì sẽ không có dữ liệu level 0 (người chỉ mới mở game/ mở tính năng mà chưa thực sự chơi) nên sẽ không thể đo được drop rate level 1, nếu muốn đo drop rate level 1 xin hãy log 1 log level 0 với status Pass lúc mới mở game/mở tính năng.
Gọi sau khi người chơi thực hiện InApp purchase trong game. Sau khi tạo bản ghi cần gọi hàm Send() để gửi bản tin đi ( new FInAppLog(...).Send(); )
Constructor của bản ghi:
string productId(!= null): id/tên của gói nạp.
decimal localizedPrice: giá của gói nạp theo đơn vị tiền tệ local (chưa nhân với hệ số store 0.7, trên server sẽ nhân hệ số sau)
string where(!= null): địa điểm nạp (nạp trong shop/ ở gói pop up cuối level,...)
string transactionId: id giao dịch.
string purchaseToken: token mà google play trả về sau giao dịch(mặc định là null cho platform IOS)
int currentLevel: level hiện đang chơi khi phát sinh nạp (khác với level tối đa của người chơi, mặc định là 0 nếu không quan tâm)
VD:
new FInappLog("pack_gem_20usd", 30.99m, "USD", "Level_45", "GPA.330...528").Send()
new FInappLog("daily_pack_1", 8400m, "KRW", "shop", "GPA.335...779", "fcdfhoogaefl ... HMtQQ", 8).Send()
Ví dụ log Inapp cho UnityEngine.Purchasing.Product - thông tin nạp mặc định của Unity:
Gọi sau khi người chơi hoàn thành xem ad trong game. Sau khi tạo bản ghi cần gọi hàm Send() để gửi bản tin đi ( new FAdLog(...).Send(); )
Constructor của bản ghi:
Constructor này đã bị deprecated với lý do chỉ cung cấp thông tin về impression mà không có các thông tin về doanh thu quảng cáo. Nếu sử dụng constructor này, bạn sẽ không xem được revenue phần quảng cáo.
AdType type: loại ad xem (AdType.interstitial, AdType.reward, ...)
string adWhere(!= null): địa điểm xem ad (xem trong shop, xem ở trong level để hồi sinh/ nhận phần thưởng,...)
int currentLevel: level hiện đang chơi khi phát sinh ad (khác với level tối đa của người chơi, mặc định là 0 nếu không quan tâm)
double? adLtv: life time value- tổng doanh thu quảng cáo của player hiện tại ( mặc định là null nếu không quan tâm)
hoặc:
AdType type: loại ad xem (AdType.interstitial, AdType.reward, ...)
string adWhere(!= null): địa điểm xem ad (xem trong shop, xem ở trong level để hồi sinh/ nhận phần thưởng,...)
string adPrecision: nguồn của doanh thu quảng cáo
BID – The revenue provided as part of the real-time auction (Not supported by FAN bidders)
RATE – The manual price the publisher assigned to an instance in the ironSource platform
CPM – Calculation based on historical instance performance, performed by ironSource platform
string adCountry: country code ISO mà mediation ghi nhận của người chơi
double adRev: doanh thu của quảng cáo
string adNetwork: mạng quảng cáo cung cấp quảng cáo vừa phát
string adMediation: tên mediation sử dụng
int currentLevel: level hiện đang chơi khi phát sinh ad (khác với level tối đa của người chơi, mặc định là 0 nếu không quan tâm)
double? adLtv: life time value- tổng doanh thu quảng cáo của player hiện tại ( mặc định là null nếu không quan tâm hoặc không lấy được)
VD:
new FAdLog(AdType.interstitial, "Video_RandomEndgame", 15).Send()
new FAdLog(AdType.reward, "Video_Revival", "BID", "PH", 0.001876, "admob", "IronSrc", 15, 16.57).Send()
Ví dụ log ad thông qua event impression của IronSrouce:
Ví dụ log ad thông qua event impression của Max:
Lưu ý:
Việc gửi event banner lên cần được sử dụng BannerLogStatistic để tối ưu số lượng bản ghi
Việc tạo log quảng cáo chỉ nên được thực hiện tại event mà mediation ghi nhận doanh thu quảng cáo, do:
Gọi hàm mở quảng cáo không đồng nghĩa với việc Mediation ghi nhận luôn impression cho ta, đôi khi mediation yêu cầu người dùng phải xem quảng cáo vài giây, hay đáp ứng điều kiện gì đó mới được tính mediation
Tại event ghi nhận doanh thu, sử dụng constructor bản đầy đủ sẽ giúp hệ thống có đầy đủ các thông tin về quảng cáo để tổng hợp, phân tích dữ liệu chính xác hơn
Gọi mỗi khi người chơi nhận/sử dụng tài nguyên trong game. Sau khi tạo bản ghi cần gọi hàm Send() để gửi bản tin đi ( new FResourceLog(...).Send(); )
Constructor của bản ghi:
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(!= null): nguồn cung cấp/tiêu thụ tài nguyên (khái quát)
string itemId(!= null): nguồn cung cấp/tiêu thụ tài nguyên (chi tiết)
string currency(!= null): loại tài nguyên người chơi nhận được (gem, gold, crystal, ...)
long amount: số lượng tài nguyên người chơi nhận được
int currentLevel: level hiện đang chơi khi phát sinh việc nhận/tiêu tài nguyên(khác với level tối đa của người chơi, mặc định là 0 nếu không quan tâm)
VD:
new FResourceLog(13, FlowType.source, "login", "login","gem", 2).Send()
new FResourceLog(5, FlowType.sink, "upgrade", "upgrade_weapon","gold", 4185).Send()
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.
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, ...). Sau khi tạo bản ghi cần gọi hàm Send() để gửi bản tin đi ( new FSessionLog(...).Send(); )
Cấu trúc hàm gồm có:
string gameMod(!= null): tên chức năng.
TimeSpan sessionTime: tổng thời gian người chơi sử dụng cho chức năng
int currentLevel: level hiện đang chơi khi phát sinh nạp (khác với level tối đa của người chơi, mặc định là 0 nếu không quan tâm)
VD:
new FSessionLog("event_christmas_day1_2021", TimeSpan.FromSeconds(153)).Send()
new FSessionLog("daily_gameplay", TimeSpan.FromMinutes(15)).Send()
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. Sau khi tạo bản ghi cần gọi hàm Send() để gửi bản tin đi ( new FFunnelLog(...).Send(); )
Cấu trúc hàm gồm có :
string funnelName(!= null): tên của biểu đồ phễu
string action(!= null): tên của mức chặn
int priority: thứ tự của mức chặn trong biểu đồ
int currentLevel: level hiện đang chơi khi phát sinh nạp (khác với level tối đa của người chơi, mặc định là 0 nếu không quan tâm)
VD:
new FFunnelLog("inapp_purchase", "whale", 17, 20).Send()
new FFunnelLog("story_line", "chapter_7", 53).Send()
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ự -> việc gửi log cần được thực hiện theo đúng trình tự priority 0 -> 1 -> 2 -> 3 -> ...
Nếu đã 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.
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, 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, ...
Khi sử dụng log này, người dùng sẽ phải tự đảm bảo logic funnel, bao gồm priority được thực hiện đúng thứ tự và mỗi priority mỗi user chỉ được log 1 lần. Nếu không thể đảm bảo được điều này, xin hãy chuyển sang sử dụng FFilteredFunnelLog.
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. Sau khi tạo bản ghi cần gọi hàm Send() để gửi bản tin đi ( new FFilteredFunnelLog(...).Send(); )
Cấu trúc hàm gồm có :
string funnelName(!= null): tên của biểu đồ phễu
string action(!= null): tên của mức chặn
int priority: thứ tự của mức chặn trong biểu đồ
int currentLevel: level hiện đang chơi khi phát sinh nạp (khác với level tối đa của người chơi, mặc định là 0 nếu không quan tâm)
VD:
new FFilteredFunnelLog("inapp_purchase", "whale", 17, 20).Send()
new FFilteredFunnelLog("story_line", "chapter_7", 53).Send()
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ự -> log sẽ không được gửi đi, thậm chí có thể vô hiệu hóa toàn bộ funnel log với funnelName là "level" từ nay về sau của player này.
Nếu đã 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 -> log sẽ không được gửi đi.
Lưu ý:
FFilteredFunnelLog, khác với FunnelLog thường, sẽ chặn log không hợp lệ khỏi việc gửi lên server, đảm bảo logic và biểu đồ Funnel được chính xác.
priority, khi sử dụng FFilteredFunnelLog, buộc phải bắt đầu đếm từ 0
Nếu như chuối priority bị dán đoạn (mất) sẽ khiến log Funnel của funnel name tương ứng bị chặn gửi từ nay về sau, vì vậy khi sử dụng log này kiến nghị gửi thừa còn hơn thiế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, 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, ...
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. Sau khi tạo bản ghi cần gọi hàm Send() để gửi bản tin đi ( new FPropertyLog(...).Send(); )
Cấu trúc hàm gồm có:
string pName(!= null): tên loại tính năng/ vật phẩm mở khóa
string pValue(!= null): loại tính năng/ vật phẩm mở khóa
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 đồ.
int currentLevel: level hiện đang chơi khi phát sinh nạp (khác với level tối đa của người chơi, mặc định là 0 nếu không quan tâm)
VD:
new FPropertyLog("weapon", "holy_moly_whack_a_moley_legendary_cannon", 99999).Send()
new FPropertyLog("level", "super_secret_hidden_level",5,69).Send()
new FPropertyLog("mission", "extremly_difficult_mission_that_nobody_can_complete",18).Send()
Chúng tôi đang thử nghiệm log này kỹ hơn, các phần biểu đồ của log này có thể chưa được hỗ trợ đầy đủ.
Gọi với sự kiện khác trong game mà các hàm log khác chưa thống kê. Đâ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. Sau khi tạo bản ghi cần gọi hàm Send() để gửi bản tin đi ( new FEventLog(...).Send(); )
Cấu trúc hàm gồm có:
string eventName(!= null): loại sự kiện
Dictionary<string, object> param: Các tham số của sự kiện
int currentLevel: level hiện đang chơi khi phát sinh nạp (khác với level tối đa của người chơi, mặc định là 0 nếu không quan tâm)
VD:
new FEventLog("weapon", new Dictionary<string, object>{{"name", "holy_moly_whack_a_moley_legendary_cannon"},{"price", 3.14}}, 99999).Send()
new FEventLog("level", new Dictionary<string, object>{{"name", ""super_secret_hidden_level""}, 69).Send()
new FEventLog("mission", new Dictionary<string, object>{{"name", "extremly_difficult_mission_that_nobody_can_complete"},{"price", 3.14}}, 18).Send()
: thống kê các level trong game.
: thống kê chỉ số nạp của người chơi.
: thống kê chỉ số xem quảng cáo của người chơi.
: thống kê các chỉ số tài nguyên mà người chơi nhận được trong game.
: thống kê khoảng thời gian chơi game của người chơi.
: 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ỳ.
: 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ỳ.
: thống kê các sự kiện khác trong game mà các hàm log khác chưa thống kê.
Chi tiết về các hàm log tự động trên có thể được xem tại .
string isoCurrencyCode: người chơi nạp thông qua đơn vị tiền tệ nào (Theo , tức là "VND" thay vì "đ", "vnđ", "đồng", ...)