> ## 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 Android SDK (v4)?

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

> [!NOTE]
>
> Before calling `initializeCustomer,` make sure you have already initialized the SDK using [Initialize SDK](https://docs.gameball.co/installation-guides/v4/android/initialize-sdk.md).

***

## Basic Customer Initialization

🔒

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

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

> [!TIP]
>
> Call `initializeCustomer` immediately after a successful login or registration flow so the customer profile stays up to date.

***

## Request Parameters

**customerId** `string` *required*

Unique identifier for the customer. This must not change for a given customer.

**email** `string`

Customer's email address.

**mobile** `string`

Customer's mobile number with country code.

**deviceToken** `string`

Push notification token (for example, FCM/Huawei token). 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`.

**customerAttributes** `CustomerAttributes`

Additional customer attributes such as name, date of birth, custom fields, etc.

**referralCode** `string`

Referral code if the customer was referred by another customer.

**isGuest** `boolean`

Guest user flag (defaults to `false`).

**osType** `string`

Operating system type. Automatically set to `"Android"`.

**sessionToken** `string`

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

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

***

## Enriching Profiles with Customer Attributes

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

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

***

## CustomerAttributes Builder

**CustomerAttributes Builder Methods**

**displayName(String)** `method`

Sets the customer's display name.

**firstName(String)** `method`

Sets the customer's first name.

**lastName(String)** `method`

Sets the customer's last name.

**email(String)** `method`

Sets the customer's email address.

**mobileNumber(String)** `method`

Sets the customer's mobile number.

**gender(String)** `method`

Sets the customer's gender.

**dateOfBirth(String)** `method`

Sets the date of birth in `
YYYY-MM-DD`

format.

**joinDate(String)** `method`

Sets the join date in `
YYYY-MM-DD`

format.

**preferredLanguage(String)** `method`

Sets the preferred language code.

**channel(String)** `method`

Sets the channel identifier (defaults to `
"mobile"`

).

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

Adds a single custom attribute key-value pair.

**customAttributes(Map)** `method`

Sets all custom attributes at once.

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

Adds a single additional attribute key-value pair.

**additionalAttributes(Map)** `method`

Sets all additional attributes at once.

***

## Recommended Usage Flow

**1. User Authenticates**

Wait until the user has successfully logged in or registered in your app.

**2. Build Attributes**

Build `CustomerAttributes` with all available information (name, contact, custom attributes).

**3. Initialize Customer**

Call `initializeCustomer` with a stable `customerId` and attributes.

**4. Proceed with Events & Rewards**

After initialization succeeds, start tracking events, showing the profile widget, and enabling rewards.


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