Device Registration

Before you can send push notifications to a user, their device must be registered with Mushu. This page covers how to get device tokens and register them.

What This Is

Device registration associates an APNs device token with a user ID. When you send a notification to a user, Mushu looks up their registered devices and sends the push to all of them.

When to Use

• After your iOS app receives a device token from APNs
• When a user logs in on a new device
• When a device token changes (rare, but possible)

Getting the Device Token (iOS)

Request notification permission and register for remote notifications:

import UserNotifications

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, error in
            if granted {
                DispatchQueue.main.async {
                    application.registerForRemoteNotifications()
                }
            }
        }
        return true
    }

    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Convert token to hex string
        let token = deviceToken.map { String(format: "%02x", $0) }.joined()

        // Register with Mushu
        registerDevice(token: token)
    }
}

Registering with Mushu

From iOS App (using API Key)

func registerDevice(token: String) {
    guard let userId = getCurrentUserId() else { return }

    let url = URL(string: "https://notify.mushucorp.com/tenants/TENANT_ID/devices")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-API-Key")

    let body: [String: Any] = [
        "user_id": userId,
        "token": token,
        "platform": "ios",
        "app_version": Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? ""
    ]
    request.httpBody = try? JSONSerialization.data(withJSONObject: body)

    URLSession.shared.dataTask(with: request) { data, response, error in
        // Handle response
    }.resume()
}

CLI (for testing)

mushu device register \
  --user USER_ID \
  --token DEVICE_TOKEN \
  --platform ios \
  --version 1.0.0

API

POST /tenants/{tenant_id}/devices
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "user_id": "user-123",
  "token": "abc123...",
  "platform": "ios",
  "app_version": "1.0.0"
}

Supported Platforms

Platform	Value
iOS	ios
watchOS	watchos

Listing Devices

mushu device list --user USER_ID

Unregistering Devices

When a user logs out, unregister their device:

mushu device unregister --user USER_ID --token DEVICE_TOKEN

Or via API:

DELETE /tenants/{tenant_id}/devices/{token}?user_id=USER_ID
X-API-Key: YOUR_API_KEY

Token Updates

If you register the same token again, Mushu updates the existing record. This is useful when the app version changes or if you need to update metadata.

Multiple Devices Per User

A user can have multiple registered devices (iPhone, iPad, Apple Watch). When you send a notification to a user, it goes to all their devices.

FAQ

When should I register the device?

Register immediately after receiving the token in didRegisterForRemoteNotificationsWithDeviceToken. Also re-register after the user logs in, in case the user ID changed.

What if the token changes?

APNs tokens rarely change, but if they do, iOS calls didRegisterForRemoteNotificationsWithDeviceToken again with the new token. Just register it as usual—Mushu will handle the update.

Should I unregister on logout?

Yes, it's good practice. This prevents notifications from going to a device after the user has logged out.

What happens to stale tokens?

When APNs reports a token as invalid (e.g., app uninstalled), Mushu automatically removes it. You don't need to manage this yourself.