Platform Integration
REST API
Game Events
Use Cases

Common Use Cases

Launch the game

  • [CLIENT_ID]: Unique identifier for the client application, provided by Playfull
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Playfull
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID]: The game's own internal user identifier

This event reports that a player has started a game session. Use it to track active sessions, start mission timers, or trigger session-based analytics.

POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"userId": "[USER_ID]", "event": "START_GAME", "time": "2023-10-24T03:42:12.650Z"},
  ],
}

Track purchase events

  • [CLIENT_ID]: Unique identifier for the client application, provided by Playfull
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Playfull
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID]: The game's own internal user identifier

Use this event to record in-app purchases or item transactions. These events feed analytics, revenue reporting, and reward rules.

POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"userId": "[USER_ID]", "event": "PURCHASE", "traits": {"usd": 1.3, "item_id": "A_GOOD_WEAPON"}, "time": "2023-10-24T03:45:00.000Z"}
  ],
}

Game Specific Use Cases

Sending custom game event data to the Playfull platform using the REST API. The examples below show common event payloads and how to structure them for analytics, mission tracking, and reward triggers.

Track game score

This event reports the final score when a game session ends. Use it for leaderboards, achievement checks, and mission completion rules.

  • [CLIENT_ID]: Unique identifier for the client application, provided by Playfull
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Playfull
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID]: The game's own internal user identifier
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"userId": "[USER_ID]", "event": "GAME_OVER", "value": 1000, "time": "2023-10-24T03:42:12.650Z"},
  ],
}

NPC Kills

This event tracks when a player kills an NPC. Use it to power mission progress, achievements, and behavior analytics.

  • [CLIENT_ID]: Unique identifier for the client application, provided by Playfull
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Playfull
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID_*]: The game's own internal user identifiers for each player in the match
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"userId": "[USER_ID_1]", "event": "KILL_NPC", "traits": {"weapon": "BASEBALL_BAT", "type": "ZOMBIE"}, "time": "2023-10-24T03:45:00.000Z"},
  ],
}

Match Ended

This event reports the end of a match and the final status for each player. It is useful for match-based missions, ranking, and post-match rewards.

  • [CLIENT_ID]: Unique identifier for the client application, provided by Playfull
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Playfull
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID_*]: The game's own internal user identifiers for each player in the match
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"userId": "[USER_ID_1]", "event": "MATCH_END", "traits": {"isSurvivor": true, "matchId": 1000}, "time": "2023-10-24T03:49:00.000Z"},
    {"userId": "[USER_ID_2]", "event": "MATCH_END", "traits": {"isSurvivor": false, "matchId": 1000}, "time": "2023-10-24T03:49:00.000Z"},
    {"userId": "[USER_ID_3]", "event": "MATCH_END", "traits": {"isSurvivor": false, "matchId": 1000}, "time": "2023-10-24T03:49:00.000Z"},
  ],
}

Reach 10 kills in 1 game

Trigger this event at match end when the player's kill count should be evaluated for missions or achievements.

  • [CLIENT_ID]: Unique identifier for the client application, provided by Playfull
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Playfull
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID]: The game's own internal user identifiers for each player in the match
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"userId": "[USER_ID]", "event": "GAME_END", "traits": {"kills": 14}, "time": "2023-10-24T03:49:00.000Z"}
  ],
}

Configure the mission to look for at least one GAME_END event, where the trait "kills" is at least 10.

Event: "GAME_END",
Filter by: "kills" >= 10
Complete when: No. of events >= 1

Score at least 1,000 in 3 matches

Use repeated MATCH_END events to evaluate multi-match missions such as "score at least 1,000 across three matches". Submit each match result so the platform can aggregate and evaluate progression.

  • [CLIENT_ID]: Unique identifier for the client application, provided by Playfull
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Playfull
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID_*]: The game's own internal user identifiers for each player in the match
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"userId": "[USER_ID]", "event": "MATCH_END", "traits": {"score": 1250}, "time": "2023-10-24T03:49:00.000Z"},
    {"userId": "[USER_ID]", "event": "MATCH_END", "traits": {"score": 1550}, "time": "2023-10-24T03:49:00.000Z"},
    {"userId": "[USER_ID]", "event": "MATCH_END", "traits": {"score": 1400}, "time": "2023-10-24T03:49:00.000Z"},
  ],
}

Configure the mission to look for at least three consecutive MATCH_END events, where the trait "score" is at least 1,000.

Event: "MATCH_END",
Filter by: "score" >= 1000
Complete when: No. of consecutive events >= 3
IntroductionBatch Sending