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

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.

Before calling initializeCustomer, make sure you have already initialized the SDK using Initialize SDK.

Basic Customer Initialization

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

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

Call initializeCustomer immediately after a successful login or registration flow so the customer profile stays up to date.

Request Parameters

string

required

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

string

Customer’s email address.

string

Customer’s mobile number with country code.

string

Push notification token (for example, FCM/Huawei token). Required if pushProvider is set.

PushProvider

Push notification provider: PushProvider.Firebase or PushProvider.Huawei. Required if deviceToken is set.

CustomerAttributes

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

string

Referral code if the customer was referred by another customer.

boolean

Guest user flag (defaults to false).

string

Operating system type. Automatically set to "Android".

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

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.

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

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

Show CustomerAttributes Builder Methods

method

Sets the customer’s display name.

method

Sets the customer’s first name.

method

Sets the customer’s last name.

method

Sets the customer’s email address.

method

Sets the customer’s mobile number.

method

Sets the customer’s gender.

method

Sets the date of birth in


YYYY-MM-DD

format.

method

Sets the join date in


YYYY-MM-DD

format.

method

Sets the preferred language code.

method

Sets the channel identifier (defaults to


“mobile”

method

Adds a single custom attribute key-value pair.

method

Sets all custom attributes at once.

method

Adds a single additional attribute key-value pair.

method

Sets all additional attributes at once.

Recommended Usage Flow

User Authenticates

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

Build Attributes

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

Initialize Customer

Call initializeCustomer with a stable customerId and attributes.

Proceed with Events & Rewards

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

Overview

Web & POS Integration

Mobile Integration

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

Basic Customer Initialization

Request Parameters

Validation Rules

Enriching Profiles with Customer Attributes

CustomerAttributes Builder

Recommended Usage Flow

​Basic Customer Initialization

​Request Parameters

​Validation Rules

​Enriching Profiles with Customer Attributes

​CustomerAttributes Builder

​Recommended Usage Flow

Basic Customer Initialization

Request Parameters

Validation Rules

Enriching Profiles with Customer Attributes

CustomerAttributes Builder

Recommended Usage Flow