How Do I Show the Profile Widget in the iOS SDK (v3)?

The Gameball profile widget shows customer points, tiers, achievements, leaderboards, available rewards, and full loyalty activity—all inside a native in-app experience. Use this when the customer taps Rewards, My Points, Loyalty, or any entry point that should open their Gameball profile.

Basic Usage

import Gameball

let request = ShowProfileRequest(
    customerId: "customer-123"
)

GameballApp.getInstance().showProfile(request, presentationStyle: .fullScreen) { success, errorMessage in
    if success {
        print("Profile displayed successfully")
    } else {
        print("Error: \(errorMessage ?? \"\")")
    }
}

let request = ShowProfileRequest(customerId: "customer-123")

GameballApp.getInstance().showProfile(
    request,
    presentationStyle: .fullScreen,
    sessionToken: "customer-token"
) { _, _ in }

import Gameball

Task {
    do {
        let request = ShowProfileRequest(customerId: "customer-123")
        try await GameballApp.getInstance().showProfile(request, presentationStyle: .fullScreen)
    } catch {
        print("Error: \(error.localizedDescription)")
    }
}

Request Parameters

String

Unique permanent identifier of the customer whose profile you want to display. Optional in v3.1.1 (omit for guest mode).

String

Opens a specific widget section (e.g., "details_earn", "details_redeem").
Defaults to the main profile view.

Hides the widget’s navigation bar. Defaults to false.

Bool

Displays a floating close button. Defaults to false.

String

Hex value (e.g., "#FF5733") for close button color. Only used when showCloseButton = true. Defaults to #CECECE.
From v3.2.1 the close button is drawn as a vector and tinted with this color, so it stays crisp at any screen scale.

String

Optional per-request session token. Overrides the global SDK token. Required in upcoming SDK v4.

String

Customer mobile number, used for channel merging. Available from v3.2.0.

String

Customer email address, used for channel merging. Available from v3.2.0.

((String) -> Void)

Handler for links the widget tags with gbExternalBrowser=true. When provided, the link is delegated to your app; otherwise the SDK opens it in the system browser. Available from v3.2.0.

Receives events the widget posts, such as game completion. Available from v3.2.0.

Validation Rules

No validation for customerId (guest mode is allowed). Provide customerId for authenticated profiles.

Advanced Configuration

Open a Specific Section

let request = ShowProfileRequest(
    customerId: "customer-123",
    openDetail: "details_earn"
)

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

Guest Mode (v3.1.1+)

// No customerId required
let guestRequest = ShowProfileRequest(
    showCloseButton: true,
    closeButtonColor: "#4CAF50"
)

GameballApp.getInstance().showProfile(guestRequest, presentationStyle: .pageSheet) { _, _ in }

Custom Close Button

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

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

Best used with openDetail to guide users directly to a specific section when navigation is hidden.

let request = ShowProfileRequest(
    customerId: "customer-123",
    hideNavigation: true,
    openDetail: "details_earn"
)

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

Handle External Links (v3.2.0+)

Links the widget tags with gbExternalBrowser=true open in the system browser by default. Provide an externalLinkCallback to handle them yourself instead (for example, to open an in-app browser or route to a custom screen):

let request = ShowProfileRequest(
    customerId: "customer-123",
    externalLinkCallback: { url in
        // Open the link your own way, e.g. an in-app browser or a custom screen
        print("External link: \(url)")
    }
)

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

When externalLinkCallback is set, the SDK delegates the link to your app and does not open the system browser.

Channel Merging (v3.2.0+)

Pass the customer’s mobile and email so Gameball can merge the customer’s channels:

let request = ShowProfileRequest(
    customerId: "customer-123",
    mobile: "+201234567890",
    email: "customer@example.com"
)

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

Pass a widgetEventCallback to react to events the widget posts, such as a customer finishing a game. Each event arrives as a [String: Any] dictionary with a top-level type and a nested metadata dictionary:

let request = ShowProfileRequest(
    customerId: "customer-123",
    widgetEventCallback: { event in
        guard let event = event else { return }   // nil means a malformed payload
        let type = event["type"] as? String       // e.g. "gameCompleted"
        let metadata = event["metadata"] as? [String: Any] ?? [:]

        if type == "gameCompleted" {
            let hasWon = metadata["hasWon"] as? Bool ?? false
            let rewardName = metadata["rewardName"] as? String
            if hasWon {
                // Refresh the customer's balance, show a win animation, etc.
            }
        }
    }
)

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

`gameCompleted` Metadata

Field	Type	Description
`hasWon`	`Bool`	Whether the customer won a reward this round
`rewardType`	`String?`	Reward category: `Default`, `Friend`, `Bonus`, `CustomText`, `Streak`, `NoReward`
`discountType`	`String?`	Coupon kind when the win is a coupon: `Fixed`, `Percentage`, `FreeShipping`, `FreeProduct`, `Custom`, `RechargeFixed`, `RechargePercentage`, `ExternalReward`. `nil` for non-coupon wins
`rewardName`	`String?`	Localized, human-readable reward name
`campaignId`	`String`	Challenge or campaign identifier
`campaignType`	`String?`	Game type: `spinTheWheel`, `slotMachine`, `quiz`, `scratchCard`, `matchCards`, `catcher`, `ticTacToe`, `shooter`, `puzzle`, `tapTarget`, `highwayDrive`

All gameCompleted values arrive as String or Bool. There are no numeric fields.

Dismiss the widget programmatically from your app. The call is a no-op when no widget is showing:

GameballApp.getInstance().hideProfile()

The widget can also dismiss itself from the web side by calling window.GameballWidget.closeWidget().

Implementation Examples

UIKit — Button Action

import UIKit
import Gameball

class ProfileViewController: UIViewController {
    
    @IBAction func showProfileTapped(_ sender: UIButton) {
        let request = ShowProfileRequest(
            customerId: "customer-123",
            showCloseButton: true,
            closeButtonColor: "#4CAF50"
        )
        
        GameballApp.getInstance().showProfile(request, presentationStyle: .fullScreen) { success, errorMessage in
            if let errorMessage = errorMessage {
                self.showAlert(message: errorMessage)
            } else if success {
                print("Profile displayed")
            }
        }
    }
    
    func showAlert(message: String) {
        let alert = UIAlertController(
            title: "Error",
            message: message,
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }
}

SwiftUI Integration

import SwiftUI
import Gameball

struct ProfileView: View {
    @State private var showError = false
    @State private var errorMessage = ""
    
    var body: some View {
        VStack {
            Button("View Rewards & Achievements") {
                showWidget()
            }
            .padding()
        }
        .alert("Error", isPresented: $showError) {
            Button("OK", role: .cancel) { }
        } message: {
            Text(errorMessage)
        }
    }
    
    func showWidget() {
        guard let vc = UIApplication.shared.windows.first?.rootViewController else {
            return
        }

        let request = ShowProfileRequest(
            customerId: "customer-123",
            showCloseButton: true
        )

        Task {
            do {
                try await GameballApp.getInstance().showProfile(
                    request,
                    presentationStyle: .fullScreen,
                    presentingViewController: vc
                )
            } catch {
                errorMessage = error.localizedDescription
                showError = true
            }
        }
    }
}

Tab Bar Integration

import UIKit
import Gameball

class MainTabBarController: UITabBarController {

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self
    }
}

extension MainTabBarController: UITabBarControllerDelegate {
    func tabBarController(_ tabBarController: UITabBarController, shouldSelect viewController: UIViewController) -> Bool {

        if viewController.tabBarItem.tag == 2 { // Rewards tab
            let request = ShowProfileRequest(
                customerId: "customer-123"
            )
            
            GameballApp.getInstance().showProfile(request, presentationStyle: .fullScreen) { _, _ in }
            return false
        }
        
        return true
    }
}

Customer Info

Points balance, tier, progress, and personal details

Reward Campaigns

Available rewards, challenges, badges, and earning opportunities

Leaderboard

Ranking, competition, and top performers

Transaction History

Full breakdown of points earned and redeemed

All widget themes, layout options, and branding styles can be customized from the Gameball Dashboard.

Best Practices

Make It Discoverable

Add the profile entry point in a visible place (e.g. tab bar, profile screen, side menu).

Use Notification Badges

Indicate new rewards or achievements to drive engagement.

Deep Link Intelligently

Use openDetail to open specific sections after qualifying user actions (e.g., after earning points).

Handle Errors Gracefully

Always provide fallback UI or messaging for network interruptions.

Showing the profile widget right after a reward is earned significantly boosts customer engagement.

Overview

Web & POS Integration

Mobile Integration

How Do I Show the Profile Widget in the iOS SDK (v3)?

Display the Profile Widget

Basic Usage

Request Parameters

Validation Rules

Advanced Configuration

Open a Specific Section

Guest Mode (v3.1.1+)

Custom Close Button

Hide Navigation

Handle External Links (v3.2.0+)

Channel Merging (v3.2.0+)

Widget Events (v3.2.0+)

`gameCompleted` Metadata

Dismiss the Widget (v3.2.0+)

Implementation Examples

UIKit — Button Action

SwiftUI Integration

Tab Bar Integration

Widget Content

Customer Info

Reward Campaigns

Leaderboard

Transaction History

Best Practices

​Display the Profile Widget

​Basic Usage

​Request Parameters

​Validation Rules

​Advanced Configuration

​Open a Specific Section

​Guest Mode (v3.1.1+)

​Custom Close Button

​Hide Navigation

​Handle External Links (v3.2.0+)

​Channel Merging (v3.2.0+)

​Widget Events (v3.2.0+)

​gameCompleted Metadata

​Dismiss the Widget (v3.2.0+)

​Implementation Examples

​UIKit — Button Action

​SwiftUI Integration

​Tab Bar Integration

​Widget Content

Customer Info

Reward Campaigns

Leaderboard

Transaction History

​Best Practices

Display the Profile Widget

Basic Usage

Request Parameters

Validation Rules

Advanced Configuration

Open a Specific Section

Guest Mode (v3.1.1+)

Custom Close Button

Hide Navigation

Handle External Links (v3.2.0+)

Channel Merging (v3.2.0+)

Widget Events (v3.2.0+)

`gameCompleted` Metadata

Dismiss the Widget (v3.2.0+)

Implementation Examples

UIKit — Button Action

SwiftUI Integration

Tab Bar Integration

Widget Content

Best Practices