Skip to main content

​
Implement Mobile Referrals

Gameball referrals for Flutter apps rely on deep links generated by a provider such as Branch or Adjust. These links help identify the referring customer when a new user installs and opens the app.
Firebase Dynamic Links are no longer supported.
Use Branch or Adjust instead.

​
Setup

1

Choose a Deep Link Provider

Use Branch or Adjust to generate referral links and handle deep/deferred linking in your Flutter app.
2

Install the Provider SDK

Add the Branch or Adjust SDKs using their official packages via pubspec.yaml and follow their integration guides for Flutter.
3

Configure Deep Linking

Set up universal links or URL schemes depending on your chosen provider (see their docs for configuration steps).
4

Connect Provider in Gameball Dashboard

In the Gameball dashboard, go to:Settings → Admin Settings → Integration → Mobile Configuration → Dynamic Link ProviderConnect your Branch or Adjust setup.
Gameball will automatically append a referral code to the generated referral links (e.g., ?referrerCode=SARAH123).
Once a user installs and opens the app through a referral link, your deep linking provider (Branch/Adjust) will pass the link parameters. You need to:
  1. Extract the referrerCode
  2. Store it temporarily (e.g., in SharedPreferences)
  3. Include it when calling registerPlayer or initializeCustomer

​
Example with Branch

// Pseudo-code example (refer to Branch docs for actual implementation)

BranchSdk.initSession().listen((data) {
  final referrerCode = data['referrerCode'];
  if (referrerCode != null) {
    // Save code to use during registration
    saveReferralCode(referrerCode);
  }
});

​
Example with Adjust

// Refer to Adjust Flutter SDK for deep link handling
Adjust.onDeeplinkResponseReceived = (String? deepLink) {
  if (deepLink != null) {
    final uri = Uri.parse(deepLink);
    final referrerCode = uri.queryParameters['referrerCode'];
    if (referrerCode != null) {
      saveReferralCode(referrerCode);
    }
  }
};

​
Register Customer with Referral

Pass the stored referral code (if any) to Gameball when registering a new customer: 
import 'package:gameball_sdk/gameball_sdk.dart';

final attributes = CustomerAttributesBuilder()
    .displayName("Jane Smith")
    .email("newuser@example.com")
    .mobile("+1234567890")
    .build();

final request = InitializeCustomerRequestBuilder()
    .customerId("new-customer-456")
    .customerAttributes(attributes)
    .referralCode(savedReferralCode) // Include captured referral code
    .build();

final gameballApp = GameballApp.getInstance();
gameballApp.initializeCustomer(request, (response, error) {
  if (error == null) {
    print("Customer registered with referral");
    clearReferralCode(); // Clear stored code after success
  } else {
    print("Error: $error");
  }
});
Clear the stored referral code after registration to avoid unintended reuse.
Customers can view and share their referral link through the Gameball widget embedded in your app. If you’re using a custom UI instead of the widget, contact Gameball support for referral link retrieval options.
Configure referral rewards and rules in your Gameball dashboard. Gameball automatically tracks referrer-referred relationships based on your configuration.

​
Referral Flow Summary

1

Referrer Gets a Link

Customer retrieves their referral link from the app (via widget or API).
2

Referrer Shares Link

The link is shared via social apps, messages, or email.
3

New User Opens Link

The app is opened via the referral deep link (Branch or Adjust).
4

App Captures Referrer Code

The SDK extracts referrerCode from the deep link.
5

New User Registers

The app calls registerPlayer or initializeCustomer, passing the referral code.
6

Rewards Are Granted

Gameball applies your referral rules to reward both the referrer and the referred customer.

​
Next Steps

  • Go-Live Checklist
  • Migration Notes