Skip to main content
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

​
customerId
String
required
Permanent unique identifier for the customer. Should never change.
​
email
String
Customer email address.
​
mobile
String
Mobile number formatted with country code.
​
deviceToken
String
Push notification token (Firebase FCM or Huawei Push Kit).
​
pushProvider
PushProvider
Push provider (.firebase or .huawei).
​
customerAttributes
CustomerAttributes
Structured attributes such as name, DOB, language, and custom fields.
​
referralCode
String
Referral code used when registering a referred customer.
​
isGuest
Bool
Indicates if this user is a guest session (default: false).
​
sessionToken
String
Optional override for global session token for this request only.

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

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