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

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

```typescript theme={null}
import { GameballApp, InitializeCustomerRequest, CustomerAttributes } from 'react-native-gameball';

const attributes: CustomerAttributes = {
  displayName: 'John Doe',
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  mobile: '+1234567890',
  gender: 'M',
  dateOfBirth: '1990-01-15',
  joinDate: '2024-01-01',
  preferredLanguage: 'en',
  customAttributes: {
    favoriteCategory: 'electronics',
    preferredChannel: 'email',
  },
  additionalAttributes: {
    country: 'USA',
    city: 'New York',
  },
};

const request: InitializeCustomerRequest = {
  customerId: 'customer-123',
  email: 'john@example.com',
  mobile: '+1234567890',
  customerAttributes: attributes,
  referralCode: 'REF123',  // Optional
  isGuest: false,          // Optional (omit for guest mode)
};

// Using async/await
try {
  const response = await GameballApp.getInstance().initializeCustomer(request);
  console.log('Customer initialized:', response.gameballId);
} catch (error) {
  console.error('Error:', error.message);
}

// With session token override
try {
  const response = await GameballApp.getInstance().initializeCustomer(request, undefined, 'customer-token');
  console.log('Customer initialized with custom token');
} catch (error) {
  console.error('Error:', error.message);
}

// Using callbacks (backward compatibility)
GameballApp.getInstance().initializeCustomer(request, {
  onSuccess: (response) => {
    console.log('Success:', response.gameballId);
  },
  onError: (error) => {
    console.error('Error:', error.message);
  }
});
```

## Request Parameters

<ParamField body="customerId" type="string" required>
  Unique identifier for the customer. This should never 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 (required if pushProvider is set).
</ParamField>

<ParamField body="pushProvider" type="'Firebase' | 'Huawei'">
  Push notification provider (required if deviceToken is set).
</ParamField>

<ParamField body="customerAttributes" type="CustomerAttributes">
  Additional customer attributes.
</ParamField>

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

<ParamField body="isGuest" type="boolean">
  Guest user flag (defaults to false).
</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 React Native SDK, passing a sessionToken parameter updates the global session token. Pass `undefined` to clear the global token, or omit it to use the current global token.
</Info>

### Validation Rules

**InitializeCustomerRequest requires:**

* `customerId` cannot be empty or whitespace
* If `deviceToken` is provided, `pushProvider` must also be specified
* If `pushProvider` is specified, `deviceToken` must also be provided

## CustomerAttributes

<Expandable title="CustomerAttributes Fields">
  <ParamField body="displayName" type="string">
    Customer's display name.
  </ParamField>

  <ParamField body="firstName" type="string">
    Customer's first name.
  </ParamField>

  <ParamField body="lastName" type="string">
    Customer's last name.
  </ParamField>

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

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

  <ParamField body="gender" type="string">
    Gender: 'M' or 'F'.
  </ParamField>

  <ParamField body="dateOfBirth" type="string">
    Date of birth in `YYYY-MM-DD` format.
  </ParamField>

  <ParamField body="joinDate" type="string">
    Join date in `YYYY-MM-DD` format.
  </ParamField>

  <ParamField body="preferredLanguage" type="string">
    Preferred language code.
  </ParamField>

  <ParamField body="customAttributes" type="Record<string, string>">
    Custom key-value pairs for additional customer data.
  </ParamField>

  <ParamField body="additionalAttributes" type="Record<string, string>">
    Additional key-value pairs for metadata.
  </ParamField>
</Expandable>

<Warning>
  **Choose an Unchangeable Customer ID**

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

## Next Steps

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