How Do I Migrate to the iOS SDK v3?

This guide walks you through migrating from Gameball iOS SDK v2 to v3.2.2.

What’s New in v3.2.2

Widget Events, Dismissal & External Links — v3.2.x keeps all v3.x code compatible. Every new capability is opt-in, so an existing integration keeps working after a version bump.

Highlights in v3.2.2

RTL Layout No Longer Leaks: the widget’s right-to-left layout direction is scoped to the widget’s own view. Opening the widget in Arabic no longer flips your app’s layout.

Highlights in v3.2.1

Vector Close Button: the close “X” is drawn as a vector tinted by closeButtonColor (default #CECECE), so it stays crisp at any screen scale.
Smaller SDK Footprint: 70 unused bundled images were removed. No public API or behavior change.

Highlights in v3.2.0

Widget Event Channel: widgetEventCallback on ShowProfileRequest receives events posted from the widget, such as gameCompleted.
Host-Initiated Dismiss: GameballApp.getInstance().hideProfile() dismisses the widget programmatically.
Web-Initiated Close: the widget can dismiss itself via window.GameballWidget.closeWidget().
External-Link Handling: links tagged gbExternalBrowser=true open in the system browser, or in your own handler via externalLinkCallback.
Channel Merging: ShowProfileRequest accepts optional mobile and email.
Diagnostic Logging: the SDK records internal diagnostic logs to aid troubleshooting. No integration changes required.

Migrate v3.1.x → v3.2.2 (Non-Breaking)

Update the SPM dependency to from: "3.2.2".
No code changes are required. Adopt the new widget capabilities only if you need them — see Show Profile Widget.

Highlights in v3.1.1

Guest Mode Fix: Profile widget works without a customer ID.
Non-Throwing ShowProfileRequest: Remove the try keyword when creating the request.
Optional customerId: Omit for guest experiences.
Session Tokens: Still supported for secure routing to v4.1.

Migrate v3.1.0 → v3.1.1 (Non-Breaking)

Update SPM dependency to from: "3.1.1".
Drop try when creating ShowProfileRequest (initializer is non-throwing).

Use guest mode when customerId is not available:

let guestRequest = ShowProfileRequest(showCloseButton: true)
GameballApp.getInstance().showProfile(guestRequest, presentationStyle: .pageSheet)

Authenticated mode stays the same:

let profileRequest = ShowProfileRequest(customerId: "customer_123")
GameballApp.getInstance().showProfile(profileRequest, presentationStyle: .fullScreen)

What’s New in v3.0.0

Modern Swift API

Native Swift API with improved type safety and better Swift idioms

Async/Await Support

Full async/await support alongside traditional callback-based APIs

Enhanced Type Safety

Stronger typing and better compile-time checks with Swift generics

Improved Performance

Optimized SDK initialization and reduced memory footprint

Breaking Changes

1. SDK Initialization

v2:

// v2 constructed a Gameball instance directly
let gameball = Gameball(
    apiKey: "api-key",
    lang: "en",
    shop: "shop-id",
    platform: "ios"
)

v3.2.2:

let config = GameballConfig(
    apiKey: "api-key",
    lang: "en",
    platform: "ios",
    shop: "shop-id",
    sessionToken: "session-token"  // Optional - New in v3.1.x
)

GameballApp.getInstance().`init`(config: config) { error in
    if let error = error {
        print("SDK init failed: \(error.localizedDescription)")
    }
}

2. Customer Registration

v2:

gameball.registerPlayer(
    playerUniqueId: "customer-123",
    referrerCode: "REF123",
    playerAttributes: attributes
) { gameballId, error in
    // Handle response
}

v3.2.2:

do {
    let request = try InitializeCustomerRequest(
        customerId: "customer-123",
        customerAttributes: attributes,
        referralCode: "REF123",
        isGuest: false
    )

    GameballApp.getInstance().initializeCustomer(request) { response, errorMessage in
        if let errorMessage = errorMessage {
            print("Error: \(errorMessage)")
        } else {
            print("Customer initialized: \(response?.gameballId ?? \"\")")
        }
    }

    // Optional: Override session token for this request
    GameballApp.getInstance().initializeCustomer(
        request,
        sessionToken: "customer-token"
    ) { _, _ in }
} catch {
    print("Validation error: \(error.localizedDescription)")
}

3. Event Tracking

v2:

// v2 sent an array of events, and params were [String: String]
let event = Event(eventName: "purchase", params: ["amount": "99.99"])

gameball.sendEvents(
    playerUniqueId: "customer-123",
    events: [event]
) { success, errorDescription in
    // Handle response
}

v3.2.2:

do {
    let event = try Event(
        events: [
            "purchase": [
                "amount": 99.99
            ]
        ],
        customerId: "customer-123"
    )

    GameballApp.getInstance().sendEvent(event) { success, errorMessage in
        if success {
            print("Event sent")
        } else if let errorMessage = errorMessage {
            print("Error: \(errorMessage)")
        }
    }

    // Optional: Override session token for this request
    GameballApp.getInstance().sendEvent(
        event,
        sessionToken: "customer-token"
    ) { _, _ in }
} catch {
    print("Validation error: \(error.localizedDescription)")
}

4. Method Name Changes

v2	v3.2.2
`Gameball(apiKey:…)` initializer	`GameballApp.getInstance().init(config:)`
`registerPlayer(playerUniqueId:…)`	`GameballApp.getInstance().initializeCustomer(_:completion:)`
`sendEvents(playerUniqueId:events:)`	`GameballApp.getInstance().sendEvent(_:completion:)`
`showProfile(playerUniqueId:…)`	`GameballApp.getInstance().showProfile(_:presentationStyle:)`
`Event(eventName:params:)`	`Event(events:customerId:)`
`playerUniqueId`	`customerId`
`playerAttributes`	`customerAttributes`
`referrerCode`	`referralCode`
`showCloseBtn`	`showCloseButton`

v2:

gameball.showProfile(
    playerUniqueId: "customer-123",
    showCloseBtn: true
) { viewController, errorMessage in
    // v2 handed you the view controller to present yourself
    if let vc = viewController {
        self.present(vc, animated: true)
    }
}

v3.2.2:

let profileRequest = ShowProfileRequest(
    customerId: "customer-123",
    showCloseButton: true,
    closeButtonColor: "#FF6B6B"
)

GameballApp.getInstance().showProfile(
    profileRequest,
    presentationStyle: .fullScreen
) { _, _ in }

// Optional: Override session token for this request
GameballApp.getInstance().showProfile(
    profileRequest,
    presentationStyle: .fullScreen,
    sessionToken: "customer-token"
) { _, _ in }

6. Error Handling

v2:

gameball.sendEvents(playerUniqueId: "customer-123", events: [event]) { success, errorDescription in
    if success != nil {
        // Success
    } else {
        // Error — v2 surfaced it as an untyped `Any?`
    }
}

v3.2.2:

GameballApp.getInstance().sendEvent(event) { success, errorMessage in
    if success {
        // Success
    } else if let errorMessage = errorMessage {
        print(errorMessage)
    }
}

7. Session Token Authentication (New in v3.1.x)

// Configure with session token
let config = GameballConfig(
    apiKey: "api-key",
    lang: "en",
    sessionToken: "session-token"  // Global token
)
GameballApp.getInstance().`init`(config: config)

// Per-request token override
GameballApp.getInstance().initializeCustomer(
    request,
    sessionToken: "override-token"
) { _, _ in }

Session tokens enable automatic v4.1 endpoint routing and enhanced security. The token is stored in memory with thread-safe access.

8. Async/Await Support (New in v3.0.0)

// Traditional callback
GameballApp.getInstance().initializeCustomer(request) { _, _ in }

// Async/await (v3.0.0+)
Task {
    do {
        let response = try await GameballApp.getInstance().initializeCustomer(request)
        // Handle success
    } catch {
        // Handle error
    }
}

// With session token override (v3.1.x+)
Task {
    do {
        let response = try await GameballApp.getInstance().initializeCustomer(
            request,
            sessionToken: "customer-token"
        )
        // Handle success
    } catch {
        // Handle error
    }
}

Migration Steps

From v3.x to v3.2.2 (No Breaking Changes)

v3.2.x is fully backward compatible with earlier v3 releases. Simply update the dependency version. Session Token support and the new widget capabilities are optional.

Update Dependency

Update your Swift Package Manager dependency to 3.2.2.

(Optional) Add Session Token

If you need enhanced security, add a session token to your configuration:

let config = GameballConfig(
    apiKey: "api-key",
    lang: "en",
    sessionToken: "your-session-token"
)

Test

Test your integration. All existing v3.0.0 code should work without changes.

From v2.x to v3.2.2

Update Dependency

Update your Swift Package Manager dependency to 3.2.2.

Update Initialization

Replace the Gameball(apiKey:…) initializer with GameballConfig + GameballApp.getInstance().init(config:).

Update Customer Registration

Replace registerPlayer() with initializeCustomer() using the new request type InitializeCustomerRequest.

Update Event Tracking

Update event creation to use the Event model and pass it to sendEvent.

Update Error Handling

Replace boolean success handlers with Result-based completion handlers to access detailed error information.

Update Show Profile

Use the non-throwing ShowProfileRequest (guest mode optional) for displaying the profile widget.

Test Thoroughly

Test all Gameball functionality (registration, events, profile, notifications, etc.) to ensure the migration is successful.

Compatibility

Minimum iOS: iOS 12.0+
Xcode: 12.0+
Swift: 5.0+

Additional Resources

GitHub Repository: https://github.com/gameballers/gameball-ios
Release history: see the gameball-ios releases page
Developer Docs: https://docs.gameball.co

If you encounter issues during migration, check the GitHub repository for known issues and solutions, or contact Gameball support.

Overview

Web & POS Integration

Mobile Integration

How Do I Migrate to the iOS SDK v3?

What’s New in v3.2.2

Highlights in v3.2.2

Highlights in v3.2.1

Highlights in v3.2.0

Migrate v3.1.x → v3.2.2 (Non-Breaking)

Highlights in v3.1.1

Migrate v3.1.0 → v3.1.1 (Non-Breaking)

What’s New in v3.0.0

Modern Swift API

Async/Await Support

Enhanced Type Safety

Improved Performance

Breaking Changes

1. SDK Initialization

2. Customer Registration

3. Event Tracking

4. Method Name Changes

5. Show Profile Widget

6. Error Handling

7. Session Token Authentication (New in v3.1.x)

8. Async/Await Support (New in v3.0.0)

Migration Steps

From v3.x to v3.2.2 (No Breaking Changes)

From v2.x to v3.2.2

Compatibility

Additional Resources

​What’s New in v3.2.2

​Highlights in v3.2.2

​Highlights in v3.2.1

​Highlights in v3.2.0

​Migrate v3.1.x → v3.2.2 (Non-Breaking)

​Highlights in v3.1.1

​Migrate v3.1.0 → v3.1.1 (Non-Breaking)

​What’s New in v3.0.0

Modern Swift API

Async/Await Support

Enhanced Type Safety

Improved Performance

​Breaking Changes

​1. SDK Initialization

​2. Customer Registration

​3. Event Tracking

​4. Method Name Changes

​5. Show Profile Widget

​6. Error Handling

​7. Session Token Authentication (New in v3.1.x)

​8. Async/Await Support (New in v3.0.0)

​Migration Steps

​From v3.x to v3.2.2 (No Breaking Changes)

​From v2.x to v3.2.2

​Compatibility

​Additional Resources

What’s New in v3.2.2

Highlights in v3.2.2

Highlights in v3.2.1

Highlights in v3.2.0

Migrate v3.1.x → v3.2.2 (Non-Breaking)

Highlights in v3.1.1

Migrate v3.1.0 → v3.1.1 (Non-Breaking)

What’s New in v3.0.0

Breaking Changes

1. SDK Initialization

2. Customer Registration

3. Event Tracking

4. Method Name Changes

5. Show Profile Widget

6. Error Handling

7. Session Token Authentication (New in v3.1.x)

8. Async/Await Support (New in v3.0.0)

Migration Steps

From v3.x to v3.2.2 (No Breaking Changes)

From v2.x to v3.2.2

Compatibility

Additional Resources