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.

Recommended size: 1200 × 800 px (3:2, the same ratio as notification images), kept under 300 KB. Link previews fetch the image when the link is unfurled, and some messaging apps skip images that are slow or too large, so a small file shows up more reliably. JPEG usually gets there for artwork and photos; use PNG for flat, text-heavy cards.

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.