Skip to main content

​
Migration Notes & Changelog

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

​
What’s New in v3.1.0

Session Token Authentication — v3.1.0 introduces optional Session Token authentication for enhanced security, with automatic v4.1 endpoint routing. This is fully backward compatible with v3.0.0.

​
New Features in v3.1.0

  • Session Token Support: Optional token-based authentication
  • Automatic Endpoint Versioning: Routes to v4.1 API when a token is present
  • Per-Request Token Override: Override the global token on individual API calls
  • Thread-Safe Token Storage: In-memory token management using a dispatch queue
  • Non-Breaking: All v3.0.0 code works unchanged

​
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: 
Gameball.configure(
    apiKey: "api-key",
    lang: "en",
    platform: "ios",
    shop: "shop-id"
)
v3.1.0: 
let config = GameballConfig(
    apiKey: "api-key",
    lang: "en",
    platform: "ios",
    shop: "shop-id",
    sessionToken: "session-token"  // Optional - New in v3.1.0
)

Gameball.shared.initialize(with: config)

​
2. Customer Registration

v2: 
Gameball.registerPlayer(
    customerId: "customer-123",
    attributes: attributes,
    referralCode: "REF123",
    isGuest: false
) { success in
    // Handle response
}
v3.1.0: 
let request = InitializeCustomerRequest(
    customerId: "customer-123",
    customerAttributes: attributes,
    referralCode: "REF123",
    isGuest: false
)

Gameball.shared.initializeCustomer(with: request) { result in
    switch result {
    case .success(let response):
        // Handle success
    case .failure(let error):
        // Handle error
    }
}

// Optional: Override session token for this request
Gameball.shared.initializeCustomer(with: request, sessionToken: "custom-token") { result in
    // Handle result
}

​
3. Event Tracking

v2: 
let event = GameballEvent()
event.customerId = "customer-123"
event.eventName = "purchase"
event.metadata = ["amount": 99.99]

Gameball.sendEvent(event) { success in
    // Handle response
}
v3.1.0: 
let event = GameballEvent(customerId: "customer-123")
event.addEvent(
    name: "purchase",
    metadata: ["amount": 99.99]
)

Gameball.shared.sendEvent(event) { result in
    switch result {
    case .success:
        // Handle success
    case .failure(let error):
        // Handle error
    }
}

// Optional: Override session token for this request
Gameball.shared.sendEvent(event, sessionToken: "custom-token") { result in
    // Handle result
}

​
4. Method Name Changes

v2v3.0.0
Gameball.configure()Gameball.shared.initialize(with:)
Gameball.registerPlayer()Gameball.shared.initializeCustomer(with:)
Gameball.sendEvent()Gameball.shared.sendEvent(_:completion:)
Gameball.sendOrder()Gameball.shared.sendOrder(_:completion:)
PlayerAttributesCustomerAttributes
PlayerRegisterResponseInitializeCustomerResponse

​
5. Show Profile Widget

v2: 
Gameball.showProfile(
    customerId: "customer-123",
    from: self
)
v3.1.0: 
let profileRequest = ShowProfileRequest(
    customerId: "customer-123",
    showCloseButton: true,
    closeButtonColor: "#FF6B6B"
)

Gameball.shared.showProfile(with: profileRequest, from: self) { result in
    // Handle result
}

// Optional: Override session token for this request
Gameball.shared.showProfile(with: profileRequest, from: self, sessionToken: "custom-token") { result in
    // Handle result
}

​
6. Error Handling

v2: 
Gameball.sendEvent(event) { success in
    if success {
        // Success
    } else {
        // Error (no details)
    }
}
v3.1.0: 
Gameball.shared.sendEvent(event) { result in
    switch result {
    case .success:
        // Success
    case .failure(let error):
        // Detailed error information
        print(error.localizedDescription)
    }
}

​
7. Session Token Authentication (New in v3.1.0)

// Configure with session token
let config = GameballConfig(
    apiKey: "api-key",
    lang: "en",
    sessionToken: "session-token"  // Global token
)
Gameball.shared.initialize(with: config)

// Per-request token override
Gameball.shared.initializeCustomer(with: request, sessionToken: "override-token") { result in
    // This request uses "override-token" instead of global token
}
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
Gameball.shared.initializeCustomer(with: request) { result in
    // Handle result
}

// Async/await (v3.0.0+)
Task {
    do {
        let response = try await Gameball.shared.initializeCustomer(with: request)
        // Handle success
    } catch {
        // Handle error
    }
}

// With session token override (v3.1.0+)
Task {
    do {
        let response = try await Gameball.shared.initializeCustomer(with: request, sessionToken: "custom-token")
        // Handle success
    } catch {
        // Handle error
    }
}

​
Migration Steps

​
From v3.0.0 to v3.1.0 (No Breaking Changes)

v3.1.0 is fully backward compatible. Simply update the dependency version. Session Token support is optional.
1

Update Dependency

Update your Podfile or Swift Package Manager configuration to use SDK v3.1.0: CocoaPods:
pod 'Gameball', '~> 3.1.0'
SPM:
Update to version 3.1.0 in Xcode package dependencies.
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"
)
3

Test

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

​
From v2.x to v3.1.0

1

Update Dependency

Update your Podfile or Swift Package Manager configuration to use SDK v3.1.0: CocoaPods:
pod 'Gameball', '~> 3.1.0'
SPM:
Update to version 3.1.0 in Xcode package dependencies.
2

Update Initialization

Replace Gameball.configure() with the new GameballConfig and initialize(with:) pattern.
3

Update Customer Registration

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

Update Event Tracking

Update event creation to use the new GameballEvent API with the addEvent() method.
5

Update Error Handling

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

Update Show Profile

Use the new ShowProfileRequest for displaying the profile widget.
7

Test Thoroughly

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

​
Compatibility

  • Minimum iOS: iOS 13.0+
  • Xcode: 14.0+
  • Swift: 5.7+
  • CocoaPods: 1.11+

​
Additional Resources

For v3.1.0-specific details, refer to the gameball-ios repository on branch release-3.1.0: https://github.com/gameballers/gameball-ios/tree/release-3.1.0
If you encounter issues during migration, check the GitHub repository for known issues and solutions, or contact Gameball support.