Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gameball.co/llms.txt

Use this file to discover all available pages before exploring further.

​
Implement Push Notifications

Gameball supports push delivery via Firebase Cloud Messaging (FCM) or Huawei Push Kit.
Use your push provider to fetch a device token, then register it with Gameball using initializeCustomer.

​
Overview

SDK Responsibilities

• Request notification permission
• Register provider token
• Link token to Gameball customer
• Handle Gameball payloads and deep links

Backend + Dashboard Responsibilities

• Configure campaigns in Gameball dashboard
• Define delivery rules and templates
• Trigger messages from Gameball automations
Notifications cover rewards, tier progression, point expiration, referral milestones, and any campaign configured in the Gameball dashboard.

​
Step 1: Request Permission

import UserNotifications

func requestNotificationPermission() {
    UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, _ in
        if granted {
            DispatchQueue.main.async {
                UIApplication.shared.registerForRemoteNotifications()
            }
        }
    }
}

​
Step 2: Get a Provider Token

Fetch a device token from your push provider, then send it to Gameball with the matching pushProvider value. 
import FirebaseMessaging
import Gameball

Messaging.messaging().token { token, error in
    guard let token = token, error == nil else { return }

    do {
        let request = try InitializeCustomerRequest(
            customerId: "customer-123",
            deviceToken: token,
            pushProvider: .firebase
        )

        GameballApp.getInstance().initializeCustomer(request) { _, _ in }
    } catch {
        print("Token registration error: \(error.localizedDescription)")
    }
}
Tokens can rotate. Re-register when the provider returns a new token.

​
Step 3: Handle Incoming Notifications

Gameball notifications include "source": "gameball" to help you detect them. 
import UserNotifications

extension AppDelegate: UNUserNotificationCenterDelegate {
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification,
        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
    ) {
        let userInfo = notification.request.content.userInfo
        if userInfo["source"] as? String == "gameball" {
            completionHandler([.banner, .sound, .badge])
        } else {
            completionHandler([])
        }
    }

    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandler completionHandler: @escaping () -> Void
    ) {
        let userInfo = response.notification.request.content.userInfo
        if userInfo["source"] as? String == "gameball" {
            handleGameballNotification(userInfo)
        }
        completionHandler()
    }

    func handleGameballNotification(_ userInfo: [AnyHashable: Any]) {
        if let deepLink = userInfo["deep_link"] as? String {
            navigateToDeepLink(deepLink)
        }
    }

    func navigateToDeepLink(_ deepLink: String) {
        // Implement your deep linking logic
    }
}

​
SwiftUI Support

Use an AppDelegate adaptor to keep the same permission and notification handling. 
import SwiftUI
import Gameball
import UserNotifications

@main
struct YourApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

​
In-App Messages

Gameball can display in-app engagement messages driven by campaigns:

Profile Widget Popups

In-app notifications are triggered when customers open the profile widget.

Native In-App Messages

Reward updates, achievement notifications, and tier promotions.
Configure in-app message templates through the Gameball dashboard.

​
Best Practices

1

Request Permission Contextually

Ask for notification permission after onboarding or when value is clear.
2

Register Token on Every Login

Device tokens change; always update them when the app launches.
3

Test on Real Devices

Simulators do not support push delivery; use physical devices for testing.
4

Deep Link Smartly

Guide users to relevant app screens when they tap notifications.