Skip to main content

​
Implement Push Notifications

Gameball uses Apple Push Notification service (APNs) to deliver reward updates, achievement alerts, campaign notifications, and in-app engagement messages.
The iOS SDK helps register device tokens and handle Gameball-originated notifications, while APNs delivery and configuration happen through your backend and the Gameball dashboard.

​
Overview: How Push Notifications Work

SDK Responsibilities

• Request notification permission
• Register device token
• Link device token to Gameball customer
• Handle Gameball notification payloads

Backend + Dashboard Responsibilities

• Configure APNs certificate
• Enable notification campaigns
• Define delivery rules and templates
• Trigger messages from Gameball campaigns
Push notifications are used for reward updates, tier progression, point expiration, referral milestones, and any campaign configured in the Gameball dashboard.

​
Step 1: Enable Push Notifications Capability

In Xcode:
  1. Select your target
  2. Go to Signing & Capabilities
  3. Click + Capability
  4. Add Push Notifications
This enables APNs support.

​
Step 2: Request Notification Permission

​
Request authorization before registering for APNs:

import UserNotifications

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

​
Step 3: Register Device Token with Gameball

When APNs returns a device token, register it with Gameball through initializeCustomer. 
import UIKit
import Gameball
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {

    UNUserNotificationCenter.current().delegate = self
    requestNotificationPermission()

    return true
}

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {

    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()

    let request = InitializeCustomerRequest(
        customerId: "customer-123",
        deviceToken: token,
        pushProvider: .apns
    )

    Gameball.shared.initializeCustomer(with: request) { result in
        switch result {
        case .success:
            print("Device token registered successfully")
        case .failure(let error):
            print("Token registration failed: \(error.localizedDescription)")
        }
    }
}

func application(
    _ application: UIApplication,
    didFailToRegisterForRemoteNotificationsWithError error: Error
) {
    print("APNs registration failed: \(error.localizedDescription)")
  }
}
Device tokens can rotate. Always call initializeCustomer again whenever APNs provides a new token.

​
Step 4: Handle Incoming Notifications

Gameball notifications include a "source": "gameball" field in the payload to help your app identify them. 
extension AppDelegate: UNUserNotificationCenterDelegate {

    // App is in foreground
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification,
        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
    ) {
        let userInfo = notification.request.content.userInfo

        if userInfo["source"] as? String == "gameball" {
            // Display Gameball notification
            completionHandler([.banner, .sound, .badge])
        } else {
            completionHandler([])
        }
    }

    // User taps notification
    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]) {
        // Navigate to profile widget or a specific screen via deep link
        if let deepLink = userInfo["deep_link"] as? String {
            navigateToDeepLink(deepLink)
        }
    }

    func navigateToDeepLink(_ deepLink: String) {
        // Implement your deep linking logic
    }
}
Deep links triggered by Gameball can open reward details, the profile widget, tier information, or your app’s custom screens.

​
SwiftUI Support

Use an AppDelegate bridge for APNs and UNUserNotificationCenter delegation. 
import SwiftUI
import Gameball
import UserNotifications
@main
struct YourApp: App {
     @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
     var body: some Scene {
         WindowGroup {
             ContentView()
         }
     }
}
class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
) -> Bool {

    UNUserNotificationCenter.current().delegate = self

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

    return true
}

// APNs registration callbacks + notification handling as above...
}

​
Configuring APNs in Gameball Dashboard

To enable Gameball to deliver push notifications, complete the APNs setup:
1

Generate APNs certificate or key

Create an APNs certificate or an Authentication Key in the Apple Developer Portal.
2

Upload to Gameball dashboard

Upload the certificate/key under Admin Settings → Integrations → Notifications.
3

Configure production vs sandbox

Ensure the correct environment matches your build configuration.
Apple resources:
  • APNs Certificate Setup
  • Handling Notifications

​
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

The iOS simulator does not support APNs.
4

Deep Link Smartly

Guide users to relevant app screens when they tap notifications.