Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gameball.co/llms.txt

Use this file to discover all available pages before exploring further.

By default, Gameball generates a unique dynamic link for every customer (via Adjust or Branch.io). The referral code is embedded inside that link itself, so when a friend clicks it, the code is carried over to the destination URL automatically. If generating a unique dynamic link per customer is too costly for your Adjust or Branch.io plan, there are two alternatives:
#AlternativeHow the referral code travels
1Single shared dynamic link + query parameterAppended to the link as ?GBReferral=CODE
2No dynamic link — manual code entryCustomer types the referral code into a form field
Instead of one unique link per customer, you configure one shared dynamic link (from Adjust or Branch.io) used for all referrers. Gameball appends each customer’s referral code to that link as a query parameter at runtime.

​
Dashboard Setup

1

Navigate to the Referral Settings

In your Gameball dashboard, go to Programs → Referrals → Settings → Referral landing page.
Referral landing page URL setting in the Gameball dashboard
2

Enter your shared dynamic link URL

Set the URL field using your base dynamic link, the parameter name you want, and the {ReferralCode} placeholder. For example:
https://yourapp.app.link/refer?GBReferral={ReferralCode}
Or with a different parameter name:
https://yourapp.app.link/refer?ReferralCode={ReferralCode}
PartWhat it is
https://yourapp.app.link/referYour base dynamic link (from Branch.io, Adjust, or your custom deep link domain)
GBReferral / ReferralCodeThe parameter name — you choose this, Gameball doesn’t enforce one
{ReferralCode}Placeholder Gameball replaces with each customer’s unique referral code at runtime

​
How It Works

After configuration, the link shown inside the widget for each referrer follows this pattern: 
https://yourapp.app.link/refer?GBReferral=ABC123
The referral code is dropped during redirection. When a friend clicks the link, they are redirected to the destination — but the GBReferral query parameter does not appear in the final URL they land on. Your client-side code must capture it before the redirect happens.

​
Client Responsibilities

  1. Read the GBReferral (or your chosen parameter name) value from the link before redirection occurs.
  2. Persist the referral code locally (e.g., in localStorage, a cookie, or session storage) so it survives until the friend completes registration.
  3. Pass the stored referral code as referrerCode in the Create/Update Customer API call when the friend signs up.

​
Alternative 2: Manual Referral Code Entry (No Dynamic Link)

This approach removes dynamic links entirely. Each customer still has their own Gameball-issued referral code — they just share it directly rather than via a link.

​
How It Works

  • The referrer shares their code through any channel (text, social media, word of mouth).
  • You add a “Referral Code” input field on your registration form.
  • When the new user submits the form, you pass the entered code as referrerCode in the Create/Update Customer API.

​
Client Responsibilities

  1. Add an optional “Referral Code” input field to the registration form:
    Registration form with an optional referral code field
  2. On account creation, include the entered value as referrerCode in the Create/Update Customer API payload: 
    POST /integrations/customers
{
  "customerId": "CUST_56789",
  "referrerCode": "ABC123",
  "customerAttributes": {
    "displayName": "Mike",
    "email": "mike@example.com"
  }
}

​
Default Flow vs. Alternatives — Comparison

The following comparison helps clarify what changes across these approaches. The final step — passing the referral code to the Gameball registration endpoint — is the same in all flows. What differs is where the code comes from and when you need to capture it.
AspectDefault (Unique Link per Customer)Alternative 1 (Shared Link + Query Param)Alternative 2 (Manual Entry)
Link per customerUnique per customerOne shared link for allNo link
Referral code visible in widget link?No — embedded inside the linkYes — shown as ?GBReferral=...N/A
Code present after redirection?Yes — read from final URLNo — must be captured before redirectN/A
When does client capture the code?After redirectionBefore redirectionAt form submission
Client passes referrerCode to registration?YesYesYes
Dynamic link costOne link generated per customerOne shared link for all customersNo dynamic links needed

​
Important Notes

Regardless of which alternative you use, referrerCode must be passed during initial customer registration. Gameball ignores it silently on subsequent updates — the customer is still created, but no referral relationship is formed.
Referral linking must occur within 5 minutes of registration to be counted. To modify this window, contact your Gameball technical point of contact.

Integrating Gameball Referrals

The standard referral flow across web, mobile, and POS channels.

Adjust Integration

Configure Adjust as your mobile deep link provider.

Branch.io Integration

Configure Branch.io as your mobile deep link provider.

Create / Update Customer API

Attach referrerCode when registering a referred friend.