> ## 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 and identify customers in your Android app

Use `initializeCustomer` whenever a user **logs in**, **registers**, or you need to **refresh their profile**. This lets Gameball attach events, rewards, and notifications to the correct customer.

<Info>
  Before calling `initializeCustomer,` make sure you have already initialized the SDK using [Initialize SDK](/installation-guides/v3/android/initialize-sdk).
</Info>

***

## Basic Customer Initialization

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

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val customerRequest = InitializeCustomerRequest.builder()
      .customerId("customer-123")
      .email("customer@example.com")
      .mobileNumber("+1234567890")
      .deviceToken("fcm-device-token")
      .pushProvider(PushProvider.Firebase)
      .build()

  GameballApp.getInstance(context).initializeCustomer(
      customerRequest,
      object : Callback<InitializeCustomerResponse> {
          override fun onSuccess(response: InitializeCustomerResponse) {
              // Customer initialized successfully
          }

          override fun onError(error: Throwable) {
              // Handle error
          }
      }
  )

  // With session token override
  GameballApp.getInstance(context).initializeCustomer(
      customerRequest,
      callback,
      sessionToken = "customer-token"
  )
  ```

  ```java Java theme={null}
  InitializeCustomerRequest customerRequest = InitializeCustomerRequest.builder()
      .customerId("customer-123")
      .email("customer@example.com")
      .mobile("+1234567890")
      .deviceToken("fcm-device-token")
      .pushProvider(PushProvider.Firebase)
      .build();

  GameballApp.getInstance(context).initializeCustomer(
      customerRequest,
      new Callback<InitializeCustomerResponse>() {
          @Override
          public void onSuccess(InitializeCustomerResponse response) {
              // Customer initialized successfully
          }

          @Override
          public void onError(Throwable error) {
              // Handle error
          }
      }
  );
  ```
</CodeGroup>

<Tip>
  Call `initializeCustomer` immediately after a successful login or registration flow so the customer profile stays up to date.
</Tip>

***

## Request Parameters

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

<ParamField body="email" type="string">
  Customer's email address.
</ParamField>

<ParamField body="mobile" type="string">
  Customer's mobile number with country code.
</ParamField>

<ParamField body="deviceToken" type="string">
  Push notification token (for example, FCM/Huawei token). Required if `pushProvider` is set.
</ParamField>

<ParamField body="pushProvider" type="PushProvider">
  Push notification provider: `PushProvider.Firebase` or `PushProvider.Huawei`. Required if `deviceToken` is set.
</ParamField>

<ParamField body="customerAttributes" type="CustomerAttributes">
  Additional customer attributes such as name, date of birth, custom fields, etc.
</ParamField>

<ParamField body="referralCode" type="string">
  Referral code if the customer was referred by another customer.
</ParamField>

<ParamField body="isGuest" type="boolean">
  Guest user flag (defaults to `false`).
</ParamField>

<ParamField body="osType" type="string">
  Operating system type. Automatically set to `"Android"`.
</ParamField>

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

### Validation Rules

**InitializeCustomerRequest requires:**

* customerId cannot be empty
* If pushProvider is set, deviceToken is required
* If deviceToken is set, pushProvider is required

<Warning>
  **Choose an Unchangeable Customer ID:** `customerId` should be a permanent identifier that never changes.
</Warning>

***

## Enriching Profiles with Customer Attributes

Use the CustomerAttributes builder to send richer profile data to Gameball.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val attributes = CustomerAttributes.builder()
      .displayName("John Doe")
      .firstName("John")
      .lastName("Doe")
      .email("john@example.com")
      .mobileNumber("+1234567890")
      .gender("male")
      .dateOfBirth("1990-01-15")
      .joinDate("2024-01-01")
      .preferredLanguage("en")
      .channel("mobile")
      .addCustomAttribute("favoriteCategory", "electronics")
      .addAdditionalAttribute("segment", "premium")
      .addAdditionalAttribute("city", "New York")
      .addAdditionalAttribute("country", "USA")
      .build()

  val customerRequest = InitializeCustomerRequest.builder()
      .customerId("customer-123")
      .email("john@example.com")
      .mobile("+1234567890")
      .customerAttributes(attributes)
      .referralCode("REF123")
      .isGuest(false)
      .build()
  ```

  ```java Java theme={null}
  CustomerAttributes attributes = CustomerAttributes.builder()
      .displayName("John Doe")
      .firstName("John")
      .lastName("Doe")
      .email("john@example.com")
      .mobileNumber("+1234567890")
      .gender("male")
      .dateOfBirth("1990-01-15")
      .joinDate("2024-01-01")
      .preferredLanguage("en")
      .channel("mobile")
      .addCustomAttribute("favoriteCategory", "electronics")
      .addAdditionalAttribute("segment", "premium")
      .addAdditionalAttribute("city", "New York")
      .addAdditionalAttribute("country", "USA")
      .build();

  InitializeCustomerRequest customerRequest = InitializeCustomerRequest.builder()
      .customerId("customer-123")
      .email("john@example.com")
      .mobile("+1234567890")
      .customerAttributes(attributes)
      .referralCode("REF123")
      .isGuest(false)
      .build();
  ```
</CodeGroup>

***

## CustomerAttributes Builder

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

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

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

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

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

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

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

    format.
  </ParamField>

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

    format.
  </ParamField>

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

  <ParamField body="channel(String)" type="method">
    Sets the channel identifier (defaults to <code>
    "mobile"</code>

    ).
  </ParamField>

  <ParamField body="addCustomAttribute(String, String)" type="method">
    Adds a single 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 a single additional attribute key-value pair.
  </ParamField>

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

***

## Recommended Usage Flow

<Steps>
  <Step title="User Authenticates">
    Wait until the user has successfully logged in or registered in your app.
  </Step>

  <Step title="Build Attributes">
    Build `CustomerAttributes` with all available information (name, contact, custom attributes).
  </Step>

  <Step title="Initialize Customer">
    Call `initializeCustomer` with a stable `customerId` and attributes.
  </Step>

  <Step title="Proceed with Events & Rewards">
    After initialization succeeds, start tracking events, showing the profile widget, and enabling rewards.
  </Step>
</Steps>