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

// Create customer attributes
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"
)

// Add custom attributes
attributes.customAttributes = [
    "loyaltyTier": "gold",
    "city": "New York"
]

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

// Initialize customer
Gameball.shared.initializeCustomer(with: request) { result in
    switch result {
    case .success(let response):
        print("Customer initialized: \(response.gameballId)")
    case .failure(let error):
        print("Error: \(error.localizedDescription)")
    }
}
Swift(Asyn/Await)
import Gameball

Task {
    do {
        let attributes = CustomerAttributes(
            displayName: "John Doe",
            email: "john@example.com",
            mobile: "+1234567890"
        )

        let request = InitializeCustomerRequest(
            customerId: "customer-123",
            customerAttributes: attributes
        )

        let response = try await Gameball.shared.initializeCustomer(with: 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
APNs push notification token.
​
pushProvider
PushProvider
Push provider (.firebase or .apns).
​
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()

    let request = InitializeCustomerRequest(
        customerId: "customer-123",
        deviceToken: token,
        pushProvider: .apns
    )

    Gameball.shared.initializeCustomer(with: request) { _ in }
}

​
With Referral Code

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

    Gameball.shared.initializeCustomer(with: request) { result in
        // Handle result
    }
}

​
Guest User

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

    Gameball.shared.initializeCustomer(with: request) { _ in }
}

​
Full Customer Profile Example

func initializeFullProfile() {
    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 = [
        "vip_level": "gold",
        "city": "New York"
    ]

    attributes.additionalAttributes = [
        "segment": "premium",
        "source": "ios_app"
    ]

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

    Gameball.shared.initializeCustomer(with: request) { result in
        // Handle result
    }
}
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.