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

# Initialize Customer Profile

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

<div className="security-banner">
  <div className="security-banner-icon">🔒</div>

  <div className="security-banner-content">
    <strong>Secure API Access:</strong> To benefit from v4.1 secure API endpoints, pass the <code>sessionToken</code> parameter when calling methods (required in upcoming SDK v4). This enables automatic routing to v4.1 secure endpoints. <a href="/api-reference/introduction-v4.1">Learn more about v4.1 →</a>
  </div>
</div>

```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

<ParamField body="customerId" type="string" required>
  Unique identifier for the customer. This should never change for a given customer.
</ParamField>

<ParamField body="customerAttributes" type="CustomerAttributes">
  Customer attributes built using `CustomerAttributesBuilder`.
</ParamField>

<ParamField body="deviceToken" type="string">
  Device token for push notifications (FCM or HMS).
</ParamField>

<ParamField body="pushProvider" type="PushProvider">
  Push notification provider: `PushProvider.Firebase` or `PushProvider.Huawei`.
</ParamField>

<ParamField body="sessionToken" type="string">
  Optional session token to override the global token for this specific request. Required in upcoming SDK v4.
</ParamField>

<Info>
  In Flutter SDK, passing a sessionToken parameter updates the global token. Pass `null` to clear, or omit to use the current global token.
</Info>

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

<Expandable title="CustomerAttributes Builder Methods">
  <ParamField body="displayName(String)" type="method">
    Sets the display name of the customer.
  </ParamField>

  <ParamField body="firstName(String)" type="method">
    Sets the first name of the customer.
  </ParamField>

  <ParamField body="lastName(String)" type="method">
    Sets the last name of the customer.
  </ParamField>

  <ParamField body="email(String)" type="method">
    Sets customer's email address.
  </ParamField>

  <ParamField body="mobile(String)" type="method">
    Sets customer's mobile number.
  </ParamField>

  <ParamField body="gender(String)" type="method">
    Sets gender: "M" for male, "F" for female.
  </ParamField>

  <ParamField body="dateOfBirth(String)" type="method">
    Sets date of birth in format `YYYY-MM-DD`.
  </ParamField>

  <ParamField body="joinDate(String)" type="method">
    Sets join date in format `YYYY-MM-DD`.
  </ParamField>

  <ParamField body="preferredLanguage(String)" type="method">
    Sets the preferred language for notifications.
  </ParamField>

  <ParamField body="addCustomAttribute(String, String)" type="method">
    Adds a custom attribute key-value pair.
  </ParamField>

  <ParamField body="customAttributes(Map)" type="method">
    Sets all custom attributes at once.
  </ParamField>

  <ParamField body="addAdditionalAttribute(String, String)" type="method">
    Adds an additional attribute key-value pair.
  </ParamField>

  <ParamField body="additionalAttributes(Map)" type="method">
    Sets all additional attributes at once.
  </ParamField>
</Expandable>

<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.
</Warning>

## 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);
```

<ParamField body="context" type="BuildContext" required>
  The Flutter BuildContext from your widget.
</ParamField>

<ParamField body="customerId" type="string">
  The customer's unique identifier (omit for guest mode).
</ParamField>

<ParamField body="openDetail" type="string">
  Specific detail to open in the profile.
</ParamField>

<ParamField body="hideNavigation" type="bool">
  Hide navigation elements.
</ParamField>

<ParamField body="showCloseButton" type="bool">
  Show close button (defaults to true).
</ParamField>

<ParamField body="closeButtonColor" type="string">
  Close button color in hex format (e.g., "#FF0000").
</ParamField>

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

## Next Steps

* [Track Customer Events](/installation-guides/v3/flutter/track-events)
* [Show Profile Widget](/installation-guides/v3/flutter/show-profile)