Skip to main content

Entry payload

Games can be launched with an entry payload attached to the link used to enter the game. The entry payload is arbitrary metadata that is made available to the game on startup.

Entry payloads enable a range of use cases, such as:

  • Carrying over onboarding choices into the full game (for example, a chosen name or cosmetic option).
  • Encoding referral or invite information, such as which player sent an invite and for which feature. This allows games to reward players for successful invitations.
  • Tracking which notification brought the player back to the game.

JestSDK.get_entry_payload()​

Returns the entry payload provided when the game was launched, or an empty dictionary if no payload was supplied.

var entry_payload = JestSDK.get_entry_payload()

if entry_payload.has("difficulty"):
    print("Starting with difficulty: %s" % entry_payload["difficulty"])

if entry_payload.get("mode", "") == "debug":
    enable_debug_mode()

Working with nested objects​

Entry payloads can contain nested objects. When accessing nested data, use standard Dictionary access:

var entry_payload = JestSDK.get_entry_payload()

# Access nested referrer data
if entry_payload.has("referrer"):
    var referrer = entry_payload["referrer"]
    if referrer is Dictionary and referrer.has("name"):
        print("Referred by: %s" % referrer["name"])

Common use cases​

Notification attribution​

When scheduling notifications, you can attach entry payload data that will be passed back when the player opens the notification:

# When scheduling
var options = JestNotificationOptions.new()
options.body = "Your crops are ready!"
options.cta_text = "Harvest"
options.identifier = "harvest_ready"
options.scheduled_in_days = 1
options.entry_payload = {
    "notification_type": "harvest_ready",
    "notification_day": 1
}
JestSDK.notifications.schedule(options)

# When the player returns via the notification
var entry_payload = JestSDK.get_entry_payload()
if entry_payload.get("notification_type", "") == "harvest_ready":
    # Show harvest UI immediately
    show_harvest_screen()

Referral tracking​

When sharing referral links, the entry payload carries referrer information:

# When sharing
var options = JestReferralOptions.new()
options.reference = "invite_friends"
options.entry_payload = {
    "referrer_id": JestSDK.player.id,
    "reward_type": "bonus_coins"
}
await JestSDK.referrals.open_referral_dialog(options)

# When the invited player enters
var entry_payload = JestSDK.get_entry_payload()
if entry_payload.has("referrer_id"):
    print("Player was referred by: %s" % entry_payload["referrer_id"])
    # Show welcome message or apply bonuses

Login with context​

When prompting login, you can pass context that will be available after the player registers:

# Prompt login with context
JestSDK.login({"source": "level_complete", "level": current_level})

# After login, retrieve the context
var entry_payload = JestSDK.get_entry_payload()
if entry_payload.get("source", "") == "level_complete":
    # Player just completed a level before registering
    show_level_complete_reward()