> ## 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.

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

> Register customers and show the Gameball profile widget

# 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.

🔒

**Secure API Access:** To benefit from v4.1 secure API endpoints, pass the `sessionToken` parameter when calling methods (required in upcoming SDK v4). This enables automatic routing to v4.1 secure endpoints. [Learn more about v4.1 →](https://docs.gameball.co/api-reference/introduction-v4.1.md)

```dart theme={null}
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

**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). Required if `pushProvider` is set.

**pushProvider** `PushProvider`

Push notification provider: `PushProvider.firebase` or `PushProvider.huawei`. Required if `deviceToken` is set. The SDK sends it to the Gameball API as `pushServiceProvider`.

**sessionToken** `string`

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

> [!NOTE]
>
> 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:

**CustomerAttributes Builder Methods**

**displayName(String)** `method`

Sets the display name of the customer.

**firstName(String)** `method`

Sets the first name of the customer.

**lastName(String)** `method`

Sets the last name of the customer.

**email(String)** `method`

Sets customer's email address.

**mobile(String)** `method`

Sets customer's mobile number.

**gender(String)** `method`

Sets gender: "M" for male, "F" for female.

**dateOfBirth(String)** `method`

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

**joinDate(String)** `method`

Sets join date in format `YYYY-MM-DD`.

**preferredLanguage(String)** `method`

Sets the preferred language for notifications.

**addCustomAttribute(String, String)** `method`

Adds a custom attribute key-value pair.

**customAttributes(Map)** `method`

Sets all custom attributes at once.

**addAdditionalAttribute(String, String)** `method`

Adds an additional attribute key-value pair.

**additionalAttributes(Map)** `method`

Sets all additional attributes at once.

> [!WARNING]
>
> **Choose an Unchangeable Customer ID**
>
> The 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:

```dart theme={null}
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);
```

**context** `BuildContext` *required*

The Flutter BuildContext from your widget.

**customerId** `string`

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

**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").

### Validation Rules

* No required fields (guest mode supported). Provide `customerId` for authenticated profiles.
* `closeButtonColor` must be in hex format (#RRGGBB) if provided

## Full Example

```dart theme={null}
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'),
        ),
      ),
    );
  }
}
```

> [!TIP]
>
> Call `initializeCustomer` when the user logs in or registers to ensure their profile is up-to-date before showing the widget.

## Next Steps

* [Track Customer Events](https://docs.gameball.co/installation-guides/v4/flutter/track-events.md)
* [Show Profile Widget](https://docs.gameball.co/installation-guides/v4/flutter/show-profile.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.