Push Tokens
Data Entity
Description
Stores device push notification tokens (FCM for Android, APNs for iOS) linked to user accounts, enabling the platform to deliver real-time push notifications to specific devices. Each user may have multiple tokens across multiple devices.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for the push token record | PKrequiredunique |
user_id |
uuid |
Reference to the user who owns this device token | required |
token |
text |
The FCM or APNs device token string used to address push notifications to this specific device | requiredunique |
platform |
enum |
The mobile platform this token belongs to, determining which push gateway (FCM or APNs) to use | required |
device_id |
string |
Unique device identifier used to deduplicate tokens per device and enable targeted revocation | required |
device_name |
string |
Human-readable device name (e.g. 'iPhone 15 Pro') for admin display in session management | - |
app_version |
string |
Version of the Meander app that registered this token, useful for debugging delivery issues | - |
is_active |
boolean |
Whether this token is currently valid for sending notifications. Set to false when FCM/APNs reports the token as invalid or the user disables push | required |
last_used_at |
datetime |
Timestamp of the last successful notification delivery to this token, used for stale token cleanup | - |
created_at |
datetime |
Timestamp when the token was first registered | required |
updated_at |
datetime |
Timestamp of the last token update or refresh | required |
Database Indexes
idx_push_tokens_user_id
Columns: user_id
idx_push_tokens_token
Columns: token
idx_push_tokens_user_device
Columns: user_id, device_id
idx_push_tokens_active_user
Columns: user_id, is_active
idx_push_tokens_platform
Columns: platform
Validation Rules
token_not_empty
error
Validation failed
valid_platform_enum
error
Validation failed
user_must_exist
error
Validation failed
device_id_required
error
Validation failed
token_uniqueness
error
Validation failed
token_max_length
error
Validation failed
Business Rules
one_token_per_device_per_user
Each user may have at most one active push token per device. When a new token is registered for the same user and device_id, the previous token must be replaced (upsert).
token_refresh_on_rotation
When FCM or APNs rotates a device token, the old token must be replaced with the new one atomically to prevent missed notifications during the transition window.
deactivate_on_invalid_response
When FCM/APNs returns an 'unregistered' or 'invalid token' error during delivery, the token must be marked is_active=false immediately to stop wasting delivery attempts.
deregister_on_push_opt_out
When a user disables push notifications via notification settings, all their active push tokens must be deactivated on the server to comply with GDPR consent withdrawal.
deregister_on_logout
When a user logs out or their session is revoked, the push token for that device must be deactivated to prevent notifications reaching a logged-out device.
multicast_requires_active_tokens
When dispatching notifications to a user, only active tokens (is_active=true) should be queried. Inactive tokens must never be included in multicast sends.
stale_token_cleanup
Tokens where last_used_at is older than 90 days and is_active is true should be flagged for cleanup to avoid accumulating unreachable tokens.