Skip to main content

​
Initialize Customer (Register/Identify)

Register or update a customer whenever they log in or register in your app. This allows Gameball to attach events and rewards to the customer profile. 
import 'package:gameball_flutter/gameball_flutter.dart';

final attributes = CustomerAttributesBuilder()
    .displayName("John Doe")
    .firstName("John")
    .lastName("Doe")
    .email("john@example.com")
    .mobile("+1234567890")
    .preferredLanguage("en")
    .addCustomAttribute("loyaltyTier", "gold")
    .addCustomAttribute("country", "USA")
    .build();

final request = InitializeCustomerRequestBuilder()
    .customerId("customer-123")
    .customerAttributes(attributes)
    .build();

final gameballApp = GameballApp.getInstance();
gameballApp.initializeCustomer(request, (response, error) {
  if (error == null) {
    print("Customer initialized successfully");
  } else {
    print("Error: $error");
  }
});

// With session token override
gameballApp.initializeCustomer(request, (response, error) {
  // Handle response
}, sessionToken: "custom-token");

​
Request Parameters

​
customerId
string
required
Unique identifier for the customer. This should never change for a given customer.
​
customerAttributes
CustomerAttributes
Customer attributes built using CustomerAttributesBuilder.
​
deviceToken
string
Device token for push notifications (FCM or HMS).
​
pushProvider
PushProvider
Push notification provider: PushProvider.Firebase or PushProvider.Huawei.
​
sessionToken
string
Optional session token to override the global token for this specific request.
In Flutter SDK, passing a sessionToken parameter updates the global token. Pass null to clear, or omit to use the current global token.

​
Validation Rules

InitializeCustomerRequest requires:
  • customerId cannot be null or empty
  • If deviceToken is provided, pushProvider must also be specified
  • If pushProvider is specified, deviceToken must also be provided

​
CustomerAttributesBuilder Methods

Build customer attributes using the builder pattern:
Choose an Unchangeable Customer IDThe customer ID should be a permanent identifier that will NEVER change. Avoid using email or phone number as the customer ID since these can be updated by users.

​
Show Customer Profile (Widget)

Display the Gameball customer profile widget to show rewards, campaigns, and leaderboards: 
import 'package:gameball_flutter/gameball_flutter.dart';

final profileRequest = ShowProfileRequestBuilder()
    .customerId("customer-123")
    .openDetail("rewards")              // optional
    .hideNavigation(false)              // optional
    .showCloseButton(true)              // optional
    .closeButtonColor("#FF6B6B")        // optional
    .widgetUrlPrefix("custom-prefix")   // optional
    .build();

final gameballApp = GameballApp.getInstance();
gameballApp.showProfile(context, profileRequest);
​
context
BuildContext
required
The Flutter BuildContext from your widget.
​
customerId
string
required
The customer’s unique identifier.
​
openDetail
string
Specific detail to open in the profile.
​
hideNavigation
bool
Hide navigation elements.
​
showCloseButton
bool
Show close button (defaults to true).
​
closeButtonColor
string
Close button color in hex format (e.g., “#FF0000”).
​
widgetUrlPrefix
string
Custom widget URL prefix.

​
Validation Rules

ShowProfileRequest requires:
  • customerId cannot be null or empty
  • closeButtonColor must be in hex format (#RRGGBB) if provided

​
Full Example

class ProfileScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('My Profile')),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            final profileRequest = ShowProfileRequestBuilder()
                .customerId("customer-123")
                .showCloseButton(true)
                .build();
                
            GameballApp.getInstance().showProfile(context, profileRequest);
          },
          child: Text('Open Gameball Profile'),
        ),
      ),
    );
  }
}
Call registerPlayer when the user logs in or registers to ensure their profile is up-to-date before showing the widget.

​
Next Steps