Push Notifications

Register Firebase or Huawei push tokens and handle Gameball-triggered notifications

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.

Swift (Firebase FCM)

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.

---