Register a device

A device must be registered before an Amazon Connect journey can deliver a notification to it. Registering stores the device's push token against the current user's profile identity, so your backend knows where to send messages.

Register with the platform push token

Obtain the token from your push provider, for example Firebase Cloud Messaging, and pass it to registerDevice:

import 'package:firebase_messaging/firebase_messaging.dart';

final token = await FirebaseMessaging.instance.getToken();
if (token != null) {
  await client.registerDevice(token: token);
}

// Register again whenever the token rotates.
FirebaseMessaging.instance.onTokenRefresh.listen((token) async {
  await client.registerDevice(token: token);
});

Requesting notification permission and receiving messages remain your application's responsibility through your push provider; the client only registers the token with your backend.

The token is the only value you provide

The library resolves the remaining device fields for you:

Registration is an idempotent operation keyed on deviceId, so calling registerDevice again with a new token updates the existing record rather than creating a second one.

The device belongs to the current identity

The registered device is stored against the principalId that your backend derives from the signed request, so a device always belongs to the identity that registered it. Your application never sends a user identifier, and one user cannot register a device against another user's profile.

Because the identity comes from Amazon Cognito identity pool credentials, registration works for guest users as well as signed-in users.

When to call registerDevice

Call registerDevice in these situations:

• After the user grants notification permission and the platform issues a push token.
• Whenever the platform rotates the token.
• After a user signs in, to move the device registration from the guest identity to the authenticated one. See Guest and authenticated users.

You do not need to call registerDevice on every application start. The registration persists until it is removed or the token changes.

Handle errors

registerDevice throws a ConnectClientException subtype when the token is invalid, the platform has no push channel, or the request cannot complete:

try {
  await client.registerDevice(token: token);
} on ConnectClientException catch (e) {
  safePrint('Failed to register device: $e');
}

Next steps

• Remove a device: de-register a device before signing a user out.