Skip to main content

Referrals

Referral links let players invite friends into your game.

You can attach an entryPayload to carry attribution or customization into the invited player's first session, and then track which invites converted (joined your game).

Conversions are grouped by reference, a stable campaign key you define (for example unlock_party_mode_v1 or tiktok_campaign_feb).

note

Attribution happens the first time a player enters your game. A player who has previously entered your game is not counted as a conversion if they later open a referral link.

Open referral dialog (OpenReferralDialog)​

Call OpenReferralDialog to open the platform share dialog for a referral link to your game.

note

OpenReferralDialog only opens the share dialog. It does not guarantee the player completes the share.

Referrals.OpenReferralDialog​

Opens the platform share dialog with your provided title/text and a link to your game.

var referrals = JestSDK.Instance.Referrals;

await referrals.OpenReferralDialog(new Referrals.OpenDialogOptions
{
    reference = "unlock_party_mode_v1",
    shareTitle = "Come play this with me!",
    shareText = "Join my game. I want to unlock Party Mode with you.",
    entryPayload = new Dictionary<string, object>
    {
        { "feature", "party_mode" },
        { "referrer", new Dictionary<string, object>
            {
                { "name", "Ava" },
                { "petName", "Pickles" }
            }
        }
    }
});

OpenDialogOptions properties​

PropertyTypeDescription
referencestringA stable campaign key you choose to label invites (required).
entryPayloadDictionary<string, object>Optional metadata passed to the invited player.
shareTitlestringOptional title for the share dialog (platform dependent).
shareTextstringOptional text for the share message.
onboardingSlugstringOptional onboarding game slug to route invited players through first.
NotificationTemplatesList<ReferralNotificationTemplate>Optional notification templates sent to the referrer when invited players convert. Each template activates at or above its MinConversionCount; the platform picks the template with the highest matching threshold and a variant from within it.

The entryPayload is embedded into the shared link. When an invited player enters your game through that link, you can read the payload via JestSDK.Instance.GetEntryPayload().

Error handling​

OpenReferralDialog throws an ArgumentException if reference is null or empty.

List referral conversions (ListReferrals)​

Call ListReferrals to retrieve referral conversions for the current player, grouped by reference.

Conversions include only invited players who complete registration.

Referrals.ListReferrals​

var referrals = JestSDK.Instance.Referrals;
var listTask = referrals.ListReferrals();

await listTask;
if (listTask.IsCompleted)
{
    var response = listTask.Result;
    foreach (var referral in response.referrals)
    {
        Debug.Log($"Reference: {referral.reference}, Registrations: {referral.registrations.Count}");
    }

    // Use response.referralsSigned for server-side verification
}

Response structure​

public class ListReferralsResponse
{
    public List<ReferralInfo> referrals;
    public string referralsSigned;  // JWS for server verification
}

public class ReferralInfo
{
    public string reference;
    public List<ReferralRegistration> registrations;  // Players who joined via this referral
}

public class ReferralRegistration
{
    public string playerId;   // The referred player's ID
    public string joinedAt;   // ISO datetime of when they joined
}

If you grant rewards for referrals, verify referralsSigned on your backend instead of trusting client-reported conversions. This is the same pattern used for Player.GetSigned() and signed purchase payloads in the Payments module.

referralsSigned is an HS256 JWS signed with your game's shared secret. For server-side verification examples, see the HTML5 SDK Referrals documentation.

Example: Unlock a feature after 3 invites​

Suppose you want to unlock a feature (for example, "Party Mode") after a player gets 3 successful invites.

Use a dedicated reference for this feature gate, for example:

  • reference: "unlock_party_mode_v1"

Client-only (not server verified)​

Simplest approach, good for low-stakes UX (cosmetics, UI hints). This can be spoofed by a modified client.

var referrals = JestSDK.Instance.Referrals;
var listTask = referrals.ListReferrals();

await listTask;
var response = listTask.Result;

// Find the referral info for our feature gate
var partyModeReferral = response.referrals
    .FirstOrDefault(r => r.reference == "unlock_party_mode_v1");

int inviteCount = partyModeReferral?.registrations?.Count ?? 0;

if (inviteCount >= 3)
{
    UnlockPartyModeLocally();
}
else
{
    ShowInviteProgress(inviteCount, required: 3);
}

For anything that affects entitlements, currency, or competitive balance, send referralsSigned to your backend for verification.

var referrals = JestSDK.Instance.Referrals;
var listTask = referrals.ListReferrals();

await listTask;
var response = listTask.Result;

// Send to your backend for verification
var unlockResult = await UnlockPartyModeServerSide(response.referralsSigned);

if (unlockResult.unlocked)
{
    UnlockPartyModeLocally();
}

See the HTML5 SDK Referrals documentation for server-side code examples.

Testing referrals​

To run a full referral loop against an uploaded build, use two sandbox users — one as the referrer, one as the invitee. See Test referrals for the step-by-step recipe.