Migrate to event-based push notification tokens

Push notification tokens now use event-based storage instead of customer profile attributes. If you use push notifications, this migration affects how tokens are stored and how your scenarios, segments, and consent workflows behave. This guide helps you prepare for and complete the migration.

New to push notifications? See Mobile push notifications for complete setup instructions. For feature details, see Multiple mobile apps per project and Multiple devices push notifications.

What changed

Push tokens moved from customer attributes to notification_state events — a new event type the SDK tracks automatically on each device. Each device generates its own event containing the Application ID, device identifier, and push token.

Before: One token per platform stored in customer attributes.
After: Multiple tokens per customer stored as events (one per app and device).

	Before	After
Storage	Customer attributes	`notification_state` events
Tokens per customer	One per platform	One per app and device
Token visibility	Customer profile	Event timeline

For technical details about event-based token storage, see Multiple mobile apps per project.

Before you upgrade

Keep these in mind as you plan:

Existing users need to open your app after the SDK update to generate new tokens — users who don't open the app won't be reachable via push until they do.
notification_state events don't count toward your Monthly Processed Events (MPE) or Monthly Event Storage (MES) quotas, so tokenTrackFrequency settings like EVERY_LAUNCH or DAILY won't impact your event costs.
ON_TOKEN_CHANGE is the recommended tokenTrackFrequency setting. If you want to target the most recently active device, use EVERY_LAUNCH — this ensures a fresh notification_state event is tracked on every app open.

Check your SDK version

Update to these minimum SDK versions:

iOS: 4.2.0
Android: 5.2.0
React Native: 4.0.0
Flutter: 2.7.0

For SDK update instructions, see:

Review your scenarios

Check all active push notification scenarios. After the upgrade, you'll need to:

Select target applications in each push notification node.
Choose a device targeting strategy (most recent device or all devices).

❗️
Important
Remove any condition nodes that check apple_push_notification_id, google_push_notification_id, or huawei_push_notification_id. These attributes no longer store tokens, so the conditions won't match.

See Multiple devices push notifications for device targeting options.

Update your segments

Find segments using these legacy attributes:

apple_push_notification_id
google_push_notification_id
huawei_push_notification_id

These attributes no longer store tokens. Rebuild segments using other customer properties or behavioral events.

Redesign cleanup workflows

Workflows that checked for empty token attributes to exclude customers need updates. The system now determines eligibility based on:

notification_state event presence.
Device activity within the validity period (90–120 days).

Contact your Customer Success Manager for migration planning help.

Handle user consent

Revoke consent

When users revoke tracking or push consent, call clearLocalCustomerData() in your SDK. This method:

Resets the local customer profile.
Generates a new device ID.
Prevents linking future events to the previous profile.

This supports GDPR compliance for consent withdrawal.

For implementation details, see:

Exclude devices automatically

You don't need manual exclusion logic. Devices stop receiving notifications when:

The app hasn't been opened within the validity period.
The app was uninstalled.
The user revoked push permissions.

Migration checklist

Update mobile SDK to minimum required version.
Review and update all push notification scenarios.
Rebuild segments using legacy push token attributes.
Update or remove cleanup workflows checking token attributes.
Implement clearLocalCustomerData() for consent revocation.
Test push notifications on updated devices.
Monitor delivery rates after migration.

What to expect

Scenario updates: Budget time to review and update existing push scenarios.

Get help

Contact your Customer Success Manager or Technical Consultant for:

Migration planning assistance.
Complex implementation guidance.
Post-migration troubleshooting.

For feature documentation, see: