Entry payload

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

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

• Carrying over onboarding choices into the full app (for example, a chosen name or cosmetic option).
• Tracking referral and invite details - specifically identifying who sent the invitation and for which feature. This allows apps to reward users for successful invitations. See Referrals and the Virality guide for more information.
• Tracking which notification brought the player back to the app.

Read the entry payload

The SDK exposes the entry payload provided when the app was launched. If no payload was supplied, the result is empty.

HTML5

JestSDK.getEntryPayload()

JestSDK.getEntryPayload(): { [key: string]: unknown };

Example:

await JestSDK.init();

const entryPayload = JestSDK.getEntryPayload();

const difficulty = entryPayload.difficulty ?? "normal";
const debugMode = entryPayload.mode === "debug";

console.log("Entry payload:", entryPayload);

Unity

JestSDK.Instance.GetEntryPayload()

var jest = JestSDK.Instance;
var entryPayload = jest.GetEntryPayload();

if (entryPayload.TryGetValue("difficulty", out var difficulty))
{
    Debug.Log($"Starting with difficulty: {difficulty}");
}

if (entryPayload.TryGetValue("mode", out var mode) && mode.ToString() == "debug")
{
    EnableDebugMode();
}

Nested values

Entry payloads can contain nested objects.

HTML5

Nested objects arrive as plain JavaScript objects. Values are typed unknown, so narrow them before use:

const entryPayload = JestSDK.getEntryPayload();

const referrer = entryPayload.referrer as { name?: string } | undefined;
if (referrer?.name) {
  console.log(`Referred by: ${referrer.name}`);
}

Unity

When accessing nested data, you may need to cast or deserialize the values:

var entryPayload = JestSDK.Instance.GetEntryPayload();

// Access nested referrer data
if (entryPayload.TryGetValue("referrer", out var referrerObj))
{
    var referrer = referrerObj as Dictionary<string, object>;
    if (referrer != null && referrer.TryGetValue("name", out var name))
    {
        Debug.Log($"Referred by: {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.

HTML5

// When scheduling
JestSDK.notifications.scheduleNotification({
  body: "Your crops are ready!",
  ctaText: "Harvest",
  priority: "high",
  identifier: "harvest_ready",
  scheduledInDays: 1,
  entryPayload: {
    notification_type: "harvest_ready",
    notification_day: "1",
  },
});

// When the player returns via the notification
const entryPayload = JestSDK.getEntryPayload();
if (entryPayload.notification_type === "harvest_ready") {
  // Show harvest UI immediately
  showHarvestScreen();
}

Unity

// When scheduling
await JestSDK.Instance.RichNotifications.ScheduleNotification(new RichNotifications.Options
{
    body = "Your crops are ready!",
    ctaText = "Harvest",
    identifier = "harvest_ready",
    scheduledInDays = 1,
    entryPayloadData = new Dictionary<string, object>
    {
        { "notification_type", "harvest_ready" },
        { "notification_day", 1 }
    }
});

// When the player returns via the notification
var entryPayload = JestSDK.Instance.GetEntryPayload();
if (entryPayload.TryGetValue("notification_type", out var notifType))
{
    if (notifType.ToString() == "harvest_ready")
    {
        // Show harvest UI immediately
        ShowHarvestScreen();
    }
}

Referral tracking

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

HTML5

// When sharing
await JestSDK.referrals.shareReferralLink({
  reference: "invite_friends",
  entryPayload: {
    referrer_id: JestSDK.getPlayer().playerId,
    reward_type: "bonus_coins",
  },
});

// When the invited player enters
const entryPayload = JestSDK.getEntryPayload();
if (entryPayload.referrer_id) {
  console.log("Player was referred by:", entryPayload.referrer_id);
  // Show welcome message or apply bonuses
}

Unity

// When sharing
await JestSDK.Instance.Referrals.OpenReferralDialog(new Referrals.OpenDialogOptions
{
    reference = "invite_friends",
    entryPayload = new Dictionary<string, object>
    {
        { "referrer_id", JestSDK.Instance.Player.id },
        { "reward_type", "bonus_coins" }
    }
});

// When the invited player enters
var entryPayload = JestSDK.Instance.GetEntryPayload();
if (entryPayload.TryGetValue("referrer_id", out var referrerId))
{
    Debug.Log($"Player was referred by: {referrerId}");
    // Show welcome message or apply bonuses
}

Login with context

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

HTML5

// Prompt login with context
JestSDK.login({
  entryPayload: {
    source: "level_complete",
    level: currentLevel,
  },
});

// After login, retrieve the context
const entryPayload = JestSDK.getEntryPayload();
if (entryPayload.source === "level_complete") {
  // Player just completed a level before registering
  showLevelCompleteReward();
}

Unity

// Prompt login with context
JestSDK.Instance.Login(new Dictionary<string, object>
{
    { "source", "level_complete" },
    { "level", currentLevel }
});

// After login, retrieve the context
var entryPayload = JestSDK.Instance.GetEntryPayload();
if (entryPayload.TryGetValue("source", out var source) && source.ToString() == "level_complete")
{
    // Player just completed a level before registering
    ShowLevelCompleteReward();
}

Test entry payload

HTML5

You can test entry payload handling during development by passing an encoded payload via the URL:

npm run dev
open http://localhost:5173/?entryPayload=%7B%22difficulty%22:%22hard%22%7D

Unity

The Unity Editor mock has no entry payload field. Test with a WebGL build in the Simulator, which lets you edit the payload the app receives on startup; mock mode's JestSDK debug menu can also edit it.