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_sdk/gameball_sdk.dart';

final attributes = CustomerAttributesBuilder()
    .displayName("John Doe")
    .firstName("John")
    .lastName("Doe")
    .email("john@example.com")
    .mobile("+1234567890")
    .preferredLanguage("en")
    .addCustomAttribute("favoriteCategory", "electronics") // User-defined custom fields
    .addAdditionalAttribute("city", "New York")
    .addAdditionalAttribute("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: "customer-token");

Request Parameters

string

required

Unique identifier for the customer. This should never change for a given customer.

CustomerAttributes

Customer attributes built using CustomerAttributesBuilder.

string

Device token for push notifications (FCM or HMS).

PushProvider

Push notification provider: PushProvider.Firebase or PushProvider.Huawei.

string

Optional session token to override the global token for this specific request. Required in upcoming SDK v4.

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:

Show CustomerAttributes Builder Methods

method

Sets the display name of the customer.

method

Sets the first name of the customer.

method

Sets the last name of the customer.

method

Sets customer’s email address.

method

Sets customer’s mobile number.

method

Sets gender: “M” for male, “F” for female.

method

Sets date of birth in format YYYY-MM-DD.

method

Sets join date in format YYYY-MM-DD.

method

Sets the preferred language for notifications.

method

Adds a custom attribute key-value pair.

method

Sets all custom attributes at once.

method

Adds an additional attribute key-value pair.

method

Sets all additional attributes at once.

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.

Display the Gameball customer profile widget to show rewards, campaigns, and leaderboards:

import 'package:gameball_sdk/gameball_sdk.dart';

final profileRequest = ShowProfileRequestBuilder()
    .customerId("customer-123")        // Optional for guest mode
    .openDetail("rewards")              // optional
    .hideNavigation(false)              // optional
    .showCloseButton(true)              // optional
    .closeButtonColor("#FF6B6B")        // optional
    .build();

final gameballApp = GameballApp.getInstance();
gameballApp.showProfile(context, profileRequest);

BuildContext

required

The Flutter BuildContext from your widget.

string

The customer’s unique identifier (omit for guest mode).

string

Specific detail to open in the profile.

Hide navigation elements.

bool

Show close button (defaults to true).

string

Close button color in hex format (e.g., “#FF0000”).

Validation Rules

No required fields (guest mode supported). Provide customerId for authenticated profiles.
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 initializeCustomer when the user logs in or registers to ensure their profile is up-to-date before showing the widget.

Overview

Web & POS Integration

Mobile Integration

How Do I Initialize the Customer Profile in the Flutter SDK (v3)?

Initialize Customer (Register/Identify)

Request Parameters

Validation Rules

CustomerAttributesBuilder Methods

Show Customer Profile (Widget)

Validation Rules

Full Example

Next Steps

​Initialize Customer (Register/Identify)

​Request Parameters

​Validation Rules

​CustomerAttributesBuilder Methods

​Show Customer Profile (Widget)

​Validation Rules

​Full Example

​Next Steps

Initialize Customer (Register/Identify)

Request Parameters

Validation Rules

CustomerAttributesBuilder Methods

Show Customer Profile (Widget)

Validation Rules

Full Example

Next Steps