Skip to main content

Referrals

Referral links let players invite friends into your game.

You can attach an entry_payload 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 (open_referral_dialog)​

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

note

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

referrals.open_referral_dialog(options)​

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

var referrals = JestSDK.referrals

var options = JestReferralOptions.new()
options.reference = "unlock_party_mode_v1"
options.share_title = "Come play this with me!"
options.share_text = "Join my game. I want to unlock Party Mode with you."
options.entry_payload = {
    "feature": "party_mode",
    "referrer": {
        "name": "Ava",
        "pet_name": "Pickles"
    }
}

var result = await referrals.open_referral_dialog(options)
if result.canceled:
    print("Player canceled the share dialog")

JestReferralOptions properties​

PropertyTypeDescription
referenceStringA stable campaign key you choose to label invites (required).
entry_payloadDictionaryOptional metadata passed to the invited player.
share_titleStringOptional title for the share dialog (platform dependent).
share_textStringOptional text for the share message.
onboarding_slugStringOptional onboarding game slug to route invited players through first.
notification_templatesArrayOptional notification templates sent to the referrer when invited players convert. Each entry is a Dictionary with min_conversion_count (int) and variants (Array of Dictionaries with body, cta_text, and optional title and image_reference). The platform picks the template with the highest matching threshold and a variant from within it.
share_imageStringOptional base64 data URL used as the OG preview image on the referral landing page. See Share image. Accepted MIME: image/png, image/jpeg, image/webp; at most 2 MB. When omitted, the game's static share image is used.

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

Share image​

Set share_image to a base64 data URL to make that image the OG preview on the referral's landing page — so when someone forwards the link or pastes it into a messaging app, they see your image instead of the game's default share card. The platform hosts the bytes on its CDN and deduplicates identical images by content hash.

Use JestUtils.texture_to_data_url(texture) (or JestUtils.image_to_data_url(image)) to build the data URL. They decompress the source first when needed, so compressed textures encode correctly — Image.save_png_to_buffer() requires an uncompressed format.

var referrals = JestSDK.referrals

var options = JestReferralOptions.new()
options.reference = "share_score_v1"
options.share_title = "I scored 9,001!"
options.share_text = "Can you beat my score?"
options.share_image = JestUtils.texture_to_data_url(my_share_texture)

var result = await referrals.open_referral_dialog(options)

Constraints: image/png, image/jpeg, or image/webp; the data URL must be at most 2 MB. If share_image is omitted, the referral link uses the game's static share image.

Error handling​

open_referral_dialog validates that reference is not empty. If validation fails, the result will have ok == false with an error message.

List referral conversions (list_referrals)​

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

Conversions include only invited players who complete registration.

referrals.list_referrals()​

var referrals = JestSDK.referrals
var result = await referrals.list_referrals()

if result.ok:
    for referral in result.referrals:
        var count = referral["registrations"].size()
        print("Reference: %s, Registrations: %d" % [referral["reference"], count])

    # Use result.referrals_signed for server-side verification

Response structure​

The result contains:

PropertyTypeDescription
referralsArray[Dictionary]Array of {reference: String, registrations: Array[{playerId: String, joinedAt: String}]} dictionaries.
referrals_signedStringJWS token for server-side verification.

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

referrals_signed 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.referrals
var result = await referrals.list_referrals()

if result.ok:
    # Find the referral info for our feature gate
    var invite_count = 0
    for referral in result.referrals:
        if referral["reference"] == "unlock_party_mode_v1":
            invite_count = referral["registrations"].size()
            break

    if invite_count >= 3:
        unlock_party_mode_locally()
    else:
        show_invite_progress(invite_count, 3)

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

var referrals = JestSDK.referrals
var result = await referrals.list_referrals()

if result.ok:
    # Send to your backend for verification
    var unlock_result = await unlock_party_mode_server_side(result.referrals_signed)

    if unlock_result.unlocked:
        unlock_party_mode_locally()

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.