Game Module
This page explains how to integrate core gameplay events (such as loading, running, pausing), sync leaderboard and achievement data. Designed for all JavaScript-based H5 games — no third-party frameworks or backend setup required.
Playol SDK provides a comprehensive behavior tracking system to support platform features like player analytics, leaderboards, achievements. Integration is lightweight, identity binding is automatic, and all data syncs directly to the platform — no custom backend needed. Focus on your game logic, and let Playol handle the rest.
📌 1. Use Cases
- Track resource loading behavior to analyze loading performance and user drop-off;
- Report in-game activity (e.g. enter, pause) to support ad optimization and behavioral analytics;
- Sync the user's scores, achievements, etc. The platform then generates rankings and rewards based on this information;
- All events are automatically tied to the logged-in user — supporting cross-device sync, resume from breakpoint, and cloud-based continuity.
🧩 2. Methods & Usage
🌀 Loading Phase
loadingStart()
Marks the beginning of resource loading — for initial loading screens only.
window.playolSDK.game.loadingStart()Use this to indicate when the game starts loading after the page opens. Useful for measuring load times and early-stage abandonment.
loadingStop()
Marks the completion of resource loading, right before gameplay begins.
window.playolSDK.game.loadingStop()📌 Notes:
- Only use for initial page load — not for level-to-level transitions;
- Call
loadingStop()just before entering the main game loop; - Ideal for first-paint analysis and load performance tracking.
▶️ Gameplay State Tracking
playStart()
Marks when gameplay begins or resumes, e.g., entering a level or continuing after pause.
window.playolSDK.game.playStart()playStop()
Marks interruptions or pauses, such as opening a menu or showing an ad.
window.playolSDK.game.playStop()📌 Best Practices:
- Call
playStart()when the user begins actively playing; - Call
playStop()during any gameplay interruption (not page exit); - Helps the platform identify user engagement patterns and session activity.
🏆 Sync Achievement Data
syncAchievement(achvKey, achvData)
Reports player progress on specific achievements.
| Parameter | Type | Required | Description |
|---|---|---|---|
achvKey | string | ✅ | Unique achievement ID (predefined) |
achvData | string | number | ✅ | Progress or completion state |
Depending on the type of achievement, achvData should be formatted differently:
| Type | Description |
|---|---|
| One-time achievement | Completing a certain task means achieving it |
| Progress achievements | Completion percentage display（0-100%） |
| Cumulative achievements | There are definite progress figures（For example 30/100） |
// One-time achievement example (Completing the first level)
window.playolSDK.game.syncAchievement('CLEAR_STAGE_1', 1)
// Progress achievement example (game completion degree 50%)
window.playolSDK.game.syncAchievement('GAME_COMPLETION', 50)
// Cumulative achievement example (collected 80 gold coins)
window.playolSDK.game.syncAchievement('COLLECT_COINS', 80)📌 Notes:
- Automatic binding
The achievement data is automatically associated with the current user (userId) and the game (gameId), without the need for additional identity marking. When the user switches accounts, logs out, or changes their identity, the system will automatically handle the data isolation and switching.
- Pre-requisite
You must first configure the achievement information (achievement key, type, maximum value, etc.) on the Developer Platform. Otherwise, the reporting will be invalid. - State calculation
The platform automatically calculates the achievement status based on the configuration (0:for not achieved / 1:for achieved)
One-time achievement: When the reporting value matching is completed, the status is updated to "Achieved".
Progress achievements: When the reported value is greater than or equal to the configured maximum value, the status is updated to "Achieved".
Cumulative achievements: When the reported value is greater than or equal to the configured maximum value, the status is updated to "Achieved". - Data update
Report multiple times and use the latest value as the standard.
The status of having achieved the goal will remain as "Achieved".
The first achievement time will be recorded and retained. - Usage scenario
It can be used to trigger logic such as front-end achievement unlock animations, reward prompts, server callbacks, etc.
- Call timing
It is recommended to invoke at key points (such as when passing the level, obtaining items, or completing tasks)
📊 Sync Leaderboard Data
syncRankData(rankData)
Submits user score or performance metrics for leaderboard ranking.
| Parameter | Type | Required | Description |
|---|---|---|---|
| rankKey | string | ✅ | Unique ranking list ID (predefined) |
rankData | string | number | ✅ | Score, Times, etc. |
Depending on the type of the ranking list, rankData should adopt different formats:
| Type | Description |
|---|---|
| Quantity | Ranked according to the size of the values (such as points, gem counts, etc.) |
| Duration | Ranked according to the size of the values (such as points, gem counts, etc.) |
| Time | According to the ranking by time points (earliest completion, latest achievement, etc.) |
// Example of the points ranking list (quantity type)
window.playolSDK.game.syncRankData('TOTAL_SCORE', 9850)
// Example of the quick passage ranking list (duration type - mm:ss.SSS format)
window.playolSDK.game.syncRankData('SPEED_RUN', '01:55.500')
// Example of the First Connection Ranking List (Time Type)
window.playolSDK.game.syncRankData('FIRST_CLEAR', '2025-01-06 12:30:45')📌 Notes:
- Automatic binding
The ranking data is automatically associated with the current user (userId) and the game (gameId). When the user changes accounts, logs out, or undergoes identity changes, the system will automatically handle the data isolation and switching.
- Pre-requisite
You must first configure the ranking information (such as ranking key, sorting rules, etc.) on the Developer Platform. Otherwise, the report will be invalid.
- Sorting rule
Reverse order: The larger the value, the higher the ranking.
Ascending order: The smaller the value, the higher the ranking. - Usage scenario
It can be used to display the overall server ranking, personal best records, season leaderboard, etc. - Call timing
It is recommended to report the data after each level is completed or when the score changes, to maintain the accuracy of the data.
🛠️ 3. Recommended Use Patterns
| Scenario | Recommended Method |
|---|---|
| Game starts loading | loadingStart() |
| Loading completes, game begins | loadingStop() |
| Gameplay starts or resumes | playStart() |
| Game pauses or opens a menu/ad | playStop() |
| Achievement unlocked | syncAchievement() |
| Score or level completion update | syncRankData() |
📦 4. FAQ
Q: What’s the difference between loadingStart() and playStart()?
A: loadingStart() is for resource loading at page entry. playStart() is for when the player enters interactive gameplay.
Q: Do sync methods overwrite existing data?
A: Yes, they update the latest value. The platform leaderboard will retain the highest or most recent valid value.
Q: Are there callbacks for sync failures?
A: Currently, all sync operations are silent. The SDK will retry if network errors occur. Promise-based responses will be supported in future versions.
🔗 Related Docs
👉 User Module | Data Module | Payment Module | Invite Module