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

To allow Gameball to track rewards, events, and progress for each user, your app must register or identify the customer after login or during onboarding.
This step links all Gameball activity to the correct player profile.

1. Basic Customer Initialization

Use initializeCustomer whenever a user logs in, registers, or updates their information.

Swift (Completion Handler)

import Gameball

do {
    let attributes = CustomerAttributes(
        displayName: "John Doe",
        firstName: "John",
        lastName: "Doe",
        email: "john@example.com",
        mobile: "+1234567890",
        customAttributes: ["favoriteCategory": "electronics"],
        additionalAttributes: ["city": "New York", "country": "USA"]
    )

    let request = try InitializeCustomerRequest(
        customerId: "customer-123",
        email: "john@example.com",
        mobile: "+1234567890",
        customerAttributes: attributes,
        referralCode: "REF123"   // Optional
    )

    GameballApp.getInstance().initializeCustomer(request) { response, errorMessage in
        if let errorMessage = errorMessage {
            print("Gameball initCustomer error: \(errorMessage)")
        } else {
            print("Customer initialized: \(response?.gameballId ?? "")")
        }
    }
} catch {
    print("Validation error: \(error.localizedDescription)")
}

Swift(Asyn/Await)

import Gameball

Task {
    do {
        let attributes = CustomerAttributes(displayName: "John Doe")
        let request = try InitializeCustomerRequest(
            customerId: "customer-123",
            customerAttributes: attributes
        )

        let response = try await GameballApp.getInstance().initializeCustomer(request)
        print("Customer initialized: \(response.gameballId)")
    } catch {
        print("Error: \(error.localizedDescription)")
    }
}

2. Request Parameters

String

required

Permanent unique identifier for the customer. Should never change.

String

Customer email address.

String

Mobile number formatted with country code.

String

Push notification token (Firebase FCM or Huawei Push Kit).

PushProvider

Push provider (.firebase or .huawei).

CustomerAttributes

Structured attributes such as name, DOB, language, and custom fields.

String

Referral code used when registering a referred customer.

Bool

Indicates if this user is a guest session (default: false).

String

Optional override for global session token for this request only. Required in upcoming SDK v4.

3. Validation Rules

InitializeCustomerRequest validates:

customerId cannot be empty
If pushProvider is provided → deviceToken is required
If deviceToken is provided → pushProvider is required

If validation fails, the SDK returns an error before sending the request.

4. Customer Attributes

You can enrich customer profiles with additional metadata.

Show CustomerAttributes Properties

String

Customer’s display name.

String

First name.

String

Last name.

String

Email address.

String

Mobile number.

String

“M” or “F”.

String

Format: YYYY-MM-DD.

String

Format: YYYY-MM-DD.

String

Language code.

[String: String]

Custom key-value pairs.

[String: String]

Extra metadata fields.

5. Advanced Examples

With Push Notifications

import Gameball
import UserNotifications

// Ask for notification permission
UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, _ in
    if granted {
        DispatchQueue.main.async {
            UIApplication.shared.registerForRemoteNotifications()
        }
    }
}

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()

    do {
        let request = try InitializeCustomerRequest(
            customerId: "customer-123",
            deviceToken: token,
            pushProvider: .firebase
        )

        GameballApp.getInstance().initializeCustomer(request) { _, _ in }
    } catch {
        print("Token validation error: \(error.localizedDescription)")
    }
}

With Referral Code

func registerCustomerWithReferral(customerId: String, referralCode: String) {
    do {
        let request = try InitializeCustomerRequest(
            customerId: customerId,
            referralCode: referralCode
        )

        GameballApp.getInstance().initializeCustomer(request) { _, _ in }
    } catch {
        print("Validation error: \(error.localizedDescription)")
    }
}

Guest User

func initializeGuestUser(sessionId: String) {
    do {
        let request = try InitializeCustomerRequest(
            customerId: "guest_\(sessionId)",
            isGuest: true
        )

        GameballApp.getInstance().initializeCustomer(request) { _, _ in }
    } catch {
        print("Validation error: \(error.localizedDescription)")
    }
}

Full Customer Profile Example

func initializeFullProfile() {
    do {
        let 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"
        )

        attributes.customAttributes = [
            "favoriteCategory": "electronics"
        ]

        attributes.additionalAttributes = [
            "segment": "premium",
            "source": "ios_app",
            "city": "New York",
            "country": "USA"
        ]

        let request = try InitializeCustomerRequest(
            customerId: "customer-123",
            email: "john@example.com",
            mobile: "+1234567890",
            customerAttributes: attributes
        )

        GameballApp.getInstance().initializeCustomer(request) { _, _ in }
    } catch {
        print("Validation error: \(error.localizedDescription)")
    }
}

Use a permanent, unchanging customer ID.
Do NOT use email or phone number as they can change.

Call initializeCustomer immediately after successful login or registration so Gameball can keep the profile updated.

Overview

Web & POS Integration

Mobile Integration

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

1. Basic Customer Initialization

2. Request Parameters

3. Validation Rules

4. Customer Attributes

5. Advanced Examples

With Push Notifications

With Referral Code

Guest User

Full Customer Profile Example

​1. Basic Customer Initialization

​2. Request Parameters

​3. Validation Rules

​4. Customer Attributes

​5. Advanced Examples

​With Push Notifications

​With Referral Code

​Guest User

​Full Customer Profile Example

1. Basic Customer Initialization

2. Request Parameters

3. Validation Rules

4. Customer Attributes

5. Advanced Examples

With Push Notifications

With Referral Code

Guest User

Full Customer Profile Example