Providers: push message structure

Altcraft Platform supports the following services for sending mobile push messages:

• Google Firebase Cloud Messaging — for Android and iOS apps
• Apple Push Notification Service — for iOS apps only
• Yandex.AppMetrica — for Android and iOS apps
• Huawei Mobile Services — for Android and iOS apps
• RuStore — for Android apps

note

Connecting the corresponding SDKs in the app is required.

tip

Yandex.AppMetrica uses Google Firebase SDK for delivery. You will need to install it in your app.

Integration with Yandex.AppMetrica is available in Altcraft Platform for importing user profiles, registering their actions and associated value (cost).

You need to verify that the app supports the Altcraft Platform push notification structure. If the format is not supported, Altcraft can adjust the message structure from its side.

Push message format

Android Firebase

note

It's possible to edit the JSON object (on request).

Adding additional data to the data object is supported. This can be done for each sending individually in the Altcraft Platform message settings.

{
	"message": {
		"token": "{{.SubscriptionID}}",
		"android": {
			"priority": "{{.Priority}}",
			"ttl": {{.TTL}},
			"data": {
				"_ac_push": "Altcraft",
				"_uid": "{{.UID}}",
				"_launch_id": "{{.LaunchID}}",
				"_title": "{{.Title}}",
				"_provider": "{{.Provider}}",
				"_body": "{{.Body}}",
				"_icon": "{{.Icon}}",
				"_click_action": "{{.ClickURL}}",
				"_color": "{{.ImageBackgroundColor}}",
				"_image": "{{.Image}}",
				"_vibration": "{{.Vibration}}",
				"_soundless": "{{.Soundless}}",
				"_hub_link": "{\"open\": \"{{.URLOpenEvent}}\", \"ack\": \"{{.URLDelivEvent}}\"}",
				"_buttons": "[{{ range $index, $button := .Actions }}{{if $index}},{{end}}{\"label\":\"{{$button.Label}}\",\"link\":\"{{$button.Link}}\"}{{ end }}]"
			}
		}
	}
}

Field	Description
token	Device push token from FCM. Unique for each device and app.
android.priority	Delivery priority: HIGH or NORMAL. Determines whether the device is woken up to receive the message.
android.ttl	Message lifetime in seconds (TTL — Time To Live). The message is not delivered after expiration. Set in account settings.
data._ac_push	Send marker. Always "Altcraft". Used by the app to identify pushes from Altcraft Platform.
data._uid	Unique message ID (SendMessageID). Contains encoded data: account, campaign, resource, channel, profile, subscription, timestamp, and checksum. Example: T2k3mN8vR4pQ1xY7zL5wJ9hF6dA0bC.
data._launch_id	Send ID within the mailing. Contains accountID, campaignID, and launch timestamp, encoded in base58. Example: 123_456_aBcDeFgHiJkLmNoPqRsTuVwXyZ. All messages in the same mailing share the same launch_id.
data._title	Push notification title. Displayed in the notification shade.
data._provider	Provider identifier. For this provider: Android Firebase.
data._body	Push notification body. Main message text.
data._icon	Notification icon URL. Displayed next to the text in the notification shade.
data._click_action	URL opened on tap. Can be a regular link or a deeplink.
data._color	Icon background color in hex format (e.g., #FF5722).
data._image	Banner image URL. Displayed as a large image in the expanded notification.
data._vibration	Forced vibration flag: true or false.
data._soundless	Silent notification flag: true or false. When true, sound is disabled.
data._hub_link	JSON object with two tracking URLs: open — URL to register the open event, ack — URL to register the delivery event. URLs are encrypted and unique per message.
data._buttons	JSON array of action buttons. Each button contains label (text) and link (URL). Generated from buttons added in message settings.

tip

_uid — unique message ID (SendMessageID). Contains encoded data about account, campaign, resource, channel, profile, subscription, and timestamp. Each push has its own unique _uid.

_launch_id — send ID within the mailing. All messages in the same mailing share the same launch_id. Contains accountID, campaignID, and launch timestamp.

iOS Firebase

note

It's possible to edit the JSON object (on request).

Adding additional data to the data object is supported. This can be done for each sending individually in the Altcraft Platform message settings.

{
	"message": {
		"token": "{{.SubscriptionID}}",
		"apns": {
			"headers": {
				"apns-expiration": "{{.TTL}}"
			},
			"payload": {
				"aps": {
					"category": "Altcraft",
					"sound": {{.Sound}},
					"mutable-content": 1,
					"alert": {
						"title": "{{.Title}}",
						"subtitle": "{{.SubTitle}}",
						"body": "{{.Body}}"
					}
				},
				"_uid": "{{.UID}}",
				"_provider": "{{.Provider}}",
				"_launch_id": "{{.LaunchID}}",
				"_ac_push": "Altcraft",
				"_click-url": "{{.ClickURL}}",
				"_media": "{{.Media}}",
				"_soundless": "{{.Soundless}}",
				"_hub_link": "{\"open\": \"{{.URLOpenEvent}}\", \"ack\": \"{{.URLDelivEvent}}\"}",
				"_buttons": "[{{ range $index, $button := .Actions }}{{if $index}},{{end}}{\"label\":\"{{$button.Label}}\",\"link\":\"{{$button.Link}}\"}{{ end }}]"
			}
		}
	}
}

Field	Description
token	Device push token from APNs via FCM. Unique for each device and app.
apns.headers.apns-expiration	Message lifetime in seconds. APNs does not deliver the message after expiration.
apns.payload.aps.category	Notification category. Always "Altcraft". Used to determine available actions on tap.
apns.payload.aps.sound	Notification sound. Default: "default". Empty string in silent mode. Can contain a sound file name from the app.
apns.payload.aps.mutable-content	Always 1. Enables Content-Extension for notification modification (e.g., image download).
apns.payload.aps.alert.title	Push notification title.
apns.payload.aps.alert.subtitle	Notification subtitle. Displayed below the title.
apns.payload.aps.alert.body	Push notification body. Main message text.
apns.payload._uid	Unique message ID (SendMessageID). Same as _uid in Android.
apns.payload._provider	Provider identifier. For this provider: iOS Firebase.
apns.payload._launch_id	Send ID within the mailing.
apns.payload._ac_push	Send marker. Always "Altcraft".
apns.payload._click-url	URL opened on tap.
apns.payload._media	Image URL for rich notification.
apns.payload._soundless	Silent notification flag: true or false.
apns.payload._hub_link	JSON object with tracking URLs: open (open) and ack (delivery).
apns.payload._buttons	JSON array of action buttons with label and link.

tip

_uid — unique message ID (SendMessageID). _launch_id — send ID within the mailing.

iOS APNS

note

It's possible to edit the JSON object (on request).

Adding additional data to the data object is supported. This can be done for each sending individually in the Altcraft Platform message settings.

{
	"aps": {
		"category": "Altcraft",
		"mutable-content": 1,
		"sound": {{.Sound}},
		"alert": {
			"title": "{{.Title}}",
			"subtitle": "{{.SubTitle}}",
			"body": "{{.Body}}"
		}
	},
	"_ac_push": "Altcraft",
	"_click-url": "{{.ClickURL}}",
	"_soundless": "{{.Soundless}}",
	"_media": "{{.Media}}",
	"_uid": "{{.UID}}",
	"_provider": "{{.Provider}}",
	"_hub_link": {
		"open": "{{.URLOpenEvent}}",
		"ack": "{{.URLDelivEvent}}"
	},
	"_buttons": "[{{ range $index, $button := .Actions }}{{if $index}},{{end}}{\"label\":\"{{$button.Label}}\",\"link\":\"{{$button.Link}}\"}{{ end }}]"
}

Field	Description
aps.category	Notification category. Always "Altcraft".
aps.mutable-content	Always 1. Enables Content-Extension.
aps.sound	Notification sound. Default: "default".
aps.alert.title	Notification title.
aps.alert.subtitle	Notification subtitle.
aps.alert.body	Notification body.
_ac_push	Send marker. Always "Altcraft".
_click-url	URL to open on tap.
_soundless	Silent notification flag.
_media	Image URL for rich notification.
_uid	Unique message ID (SendMessageID).
_provider	Provider identifier: iOS APNS.
_hub_link.open	URL to register the open event.
_hub_link.ack	URL to register the delivery event.
_buttons	JSON array of action buttons.

AppMetrica iOS

note

It's possible to edit the JSON object (on request).

Adding additional data to the data object is supported. This can be done for each sending individually in the Altcraft Platform message settings.

{
	"push_batch_request": {
		"group_id": 97737,
		"tag": "tag",
		"batch": [
			{
				"messages": {
					"iOS": {
						"silent": true/false,
						"content": {
							"title": "Title",
							"text": "Body",
							"badge": 0-999,
							"expiration": 0,
							"data": "{\"hub_link\":{\"ack\":\"URLDelivEvent\",\"open\":\"URLOpenEvent\"},\"icon\":\"Icon\",\"media\":\"Media\"}"
						},
						"open_action": {
							"url": "URL",
							"deeplink": "Deeplink"
						}
					}
				},
				"devices": [
					{
						"id_values": ["SubscriptionID"],
						"id_type": "ios_push_token"
					}
				]
			}
		]
	}
}

Field	Description
push_batch_request.group_id	Group ID in AppMetrica. Set when configuring the channel.
push_batch_request.tag	Mailing tag. Used to group sends in AppMetrica.
push_batch_request.batch	Array of messages to send.
messages.iOS.silent	Silent push flag: true — background delivery without notification, false — standard notification.
messages.iOS.content.title	Notification title.
messages.iOS.content.text	Notification body.
messages.iOS.content.badge	App badge counter. Range: 0–999.
messages.iOS.content.expiration	Message lifetime in seconds. 0 — message is not stored if the device is unavailable.
messages.iOS.content.data	JSON string with additional data: hub_link (tracking), icon (icon), media (image).
messages.iOS.open_action.url	URL to open on tap (regular link).
messages.iOS.open_action.deeplink	Deeplink to open on tap.
devices.id_values	Array of device push tokens.
devices.id_type	Identifier type: ios_push_token for iOS.

note

In AppMetrica iOS, _uid and _launch_id fields are not passed directly in the message structure. Tracking is handled through hub_link inside the data field.

AppMetrica Android

note

It's possible to edit the JSON object (on request).

Adding additional data to the data object is supported. This can be done for each sending individually in the Altcraft Platform message settings.

{
	"push_batch_request": {
		"group_id": 97737,
		"tag": "tag",
		"batch": [
			{
				"messages": {
					"android": {
						"silent": true/false,
						"content": {
							"title": "Title",
							"text": "Body",
							"time_to_live": 0,
							"image": "Icon",
							"icon_background": "IconBackground",
							"banner": "Banner",
							"led_color": "LEDColor",
							"data": "{\"hub_link\":{\"ack\":\"URLDelivEvent\",\"open\":\"URLOpenEvent\"}}"
						},
						"open_action": {
							"url": "URL",
							"deeplink": "Deeplink"
						}
					}
				},
				"devices": [
					{
						"id_values": ["SubscriptionID"],
						"id_type": "google_aid"
					}
				]
			}
		]
	}
}

Field	Description
push_batch_request.group_id	Group ID in AppMetrica.
push_batch_request.tag	Mailing tag.
push_batch_request.batch	Array of messages to send.
messages.android.silent	Silent push flag.
messages.android.content.title	Notification title.
messages.android.content.text	Notification body.
messages.android.content.time_to_live	Message lifetime in seconds.
messages.android.content.image	Notification icon URL.
messages.android.content.icon_background	Icon background color in hex format.
messages.android.content.banner	Banner image URL.
messages.android.content.led_color	LED indicator color in hex format.
messages.android.content.data	JSON string with tracking data: hub_link contains URLs for ack (delivery) and open (open) events.
messages.android.open_action.url	URL to open on tap.
messages.android.open_action.deeplink	Deeplink to open on tap.
devices.id_values	Array of device identifiers (Google AID).
devices.id_type	Identifier type: google_aid for Android.

note

In AppMetrica Android, _uid and _launch_id fields are not passed directly in the message structure. Tracking is handled through hub_link inside the data field.

HMS Android

note

It's possible to edit the JSON object (on request).

Adding additional data to the data object is supported. This can be done for each sending individually in the Altcraft Platform message settings.

{
	"message": {
		"token": ["{{.SubscriptionID}}"],
		"data": {
			"_ac_push": "Altcraft",
			"_title": "{{.Title}}",
			"_uid": "{{.UID}}",
			"_provider": "{{.Provider}}",
			"_body": "{{.Body}}",
			"_launch_id": "{{.LaunchID}}",
			"_vibration": "{{.Vibration}}",
			"_soundless": "{{.Soundless}}",
			"_hub_link": "{\"open\": \"{{.URLOpenEvent}}\", \"ack\": \"{{.URLDelivEvent}}\"}",
			"_icon": "{{.Icon}}",
			"_click_action": "{{.ClickURL}}",
			"_color": "{{.ImageBackgroundColor}}",
			"_image": "{{.Image}}",
			"_buttons": "[{{ range $index, $button := .Actions }}{{if $index}},{{end}}{\"label\":\"{{$button.Label}}\",\"link\":\"{{$button.Link}}\"}{{ end }}]"
		},
		"android": {
			"urgency": "HIGH",
			"ttl": {{.TTL}}
		}
	}
}

Field	Description
message.token	Array of HMS device push tokens. Unlike Firebase, the token is passed as an array.
data._ac_push	Send marker. Always "Altcraft".
data._title	Notification title.
data._uid	Unique message ID (SendMessageID).
data._provider	Provider identifier: Android HMS.
data._body	Notification body.
data._launch_id	Send ID within the mailing.
data._vibration	Forced vibration flag.
data._soundless	Silent notification flag.
data._hub_link	JSON object with tracking URLs: open and ack.
data._icon	Notification icon URL.
data._click_action	URL to open on tap.
data._color	Icon background color in hex format.
data._image	Banner image URL.
data._buttons	JSON array of action buttons.
android.urgency	Delivery urgency. Always HIGH.
android.ttl	Message lifetime in seconds.

HMS iOS

note

It's possible to edit the JSON object (on request).

Adding additional data to the data object is supported. This can be done for each sending individually in the Altcraft Platform message settings.

{
	"message": {
		"token": ["{{.SubscriptionID}}"],
		"apns": {
			"headers": {
				"apns-expiration": "{{.TTL}}"
			},
			"payload": {
				"aps": {
					"category": "Altcraft",
					"mutable-content": 1,
					"sound": {{.Sound}},
					"alert": {
						"title": "{{.Title}}",
						"subtitle": "{{.SubTitle}}",
						"body": "{{.Body}}"
					}
				},
				"_ac_push": "Altcraft",
				"_provider": "{{.Provider}}",
				"_click-url": "{{.ClickURL}}",
				"_soundless": "{{.Soundless}}",
				"_uid": "{{.UID}}",
				"_media": "{{.Media}}",
				"_hub_link": {
					"open": "{{.URLOpenEvent}}",
					"ack": "{{.URLDelivEvent}}"
				},
				"_buttons": "[{{ range $index, $button := .Actions }}{{if $index}},{{end}}{\"label\":\"{{$button.Label}}\",\"link\":\"{{$button.Link}}\"}{{ end }}]"
			},
			"hms_options": {
				"target_user_type": 1
			}
		}
	}
}

Field	Description
message.token	Array of HMS device push tokens.
apns.headers.apns-expiration	Message lifetime in seconds.
apns.payload.aps.category	Notification category. Always "Altcraft".
apns.payload.aps.mutable-content	Always 1. Enables Content-Extension.
apns.payload.aps.sound	Notification sound.
apns.payload.aps.alert.title	Notification title.
apns.payload.aps.alert.subtitle	Notification subtitle.
apns.payload.aps.alert.body	Notification body.
apns.payload._ac_push	Send marker.
apns.payload._provider	Provider identifier: iOS HMS.
apns.payload._click-url	URL to open on tap.
apns.payload._soundless	Silent notification flag.
apns.payload._uid	Unique message ID (SendMessageID).
apns.payload._media	Image URL for rich notification.
apns.payload._hub_link.open	URL to register the open event.
apns.payload._hub_link.ack	URL to register the delivery event.
apns.payload._buttons	JSON array of action buttons.
apns.hms_options.target_user_type	Target user type in HMS. Always 1.

RuStore Android

note

It's possible to edit the JSON object (on request).

Adding additional data to the data object is supported. This can be done for each sending individually in the Altcraft Platform message settings.

{
	"message": {
		"token": "{{.SubscriptionID}}",
		"data": {
			"_ac_push": "Altcraft",
			"_title": "{{.Title}}",
			"_uid": "{{.UID}}",
			"_provider": "{{.Provider}}",
			"_body": "{{.Body}}",
			"_icon": "{{.Icon}}",
			"_image": "{{.Image}}",
			"_launch_id": "{{.LaunchID}}",
			"_vibration": "{{.Vibration}}",
			"_soundless": "{{.Soundless}}",
			"_color": "{{.ImageBackgroundColor}}",
			"_click_action": "{{.ClickURL}}",
			"_hub_link": "{\"open\": \"{{.URLOpenEvent}}\", \"ack\": \"{{.URLDelivEvent}}\"}",
			"_buttons": "[{{ range $index, $button := .Actions }}{{if $index}},{{end}}{\"label\":\"{{$button.Label}}\",\"link\":\"{{$button.Link}}\"}{{ end }}]"
		},
		"android": {
			"priority": "HIGH",
			"ttl": {{.TTL}}
		}
	}
}

Field	Description
message.token	RuStore device push token.
data._ac_push	Send marker. Always "Altcraft".
data._title	Notification title.
data._uid	Unique message ID (SendMessageID).
data._provider	Provider identifier: Android RuStore.
data._body	Notification body.
data._icon	Notification icon URL.
data._image	Banner image URL.
data._launch_id	Send ID within the mailing.
data._vibration	Forced vibration flag.
data._soundless	Silent notification flag.
data._color	Icon background color in hex format.
data._click_action	URL to open on tap.
data._hub_link	JSON object with tracking URLs: open and ack.
data._buttons	JSON array of action buttons.
android.priority	Delivery priority. Always HIGH.
android.ttl	Message lifetime in seconds.

tip

_uid — unique message ID (SendMessageID). _launch_id — send ID within the mailing.

Common fields across all providers

The fields below are present in Altcraft Platform push message structures regardless of the provider.

Identifiers

Field	Description
_uid	SendMessageID — unique identifier for each sent message. Contains encoded data: account, campaign, resource, channel, profile, subscription IDs, send timestamp, and checksum. Starts with a version prefix: T (Full), U (Unique), E (Email). Example: T2k3mN8vR4pQ1xY7zL5wJ9hF6dA0bC.
_launch_id	Send ID within the mailing. All messages in the same mailing share the same launch_id. Contains accountID, campaignID, and launch timestamp, encoded in base58 (Flickr alphabet). Format: accountID_campaignID_timestamp. Example: 123_456_aBcDeFgHiJkLmNoPqRsTuVwXyZ.
_ac_push	Send marker from Altcraft Platform. Always "Altcraft". Used by the app to identify push notifications from the platform.
_provider	Provider identifier through which the message was sent. Examples: Android Firebase, iOS Firebase, iOS APNS, Android HMS, Android RuStore.

Notification content

Field	Description
_title / title	Push notification title. Displayed in the device notification shade.
_body / text / body	Push notification body. Main message text.
_subtitle / subtitle	Notification subtitle. iOS only. Displayed below the title.
_icon / image	Notification icon URL. Displayed next to the text in the notification shade.
_image / banner / _media	Banner image URL. Displayed as a large image in the expanded notification.
_click_action / _click-url / url	URL opened on tap. Can be a regular link or a deeplink.
_color / icon_background	Icon background color in hex format (e.g., #FF5722).

Delivery control

Field	Description
ttl / apns-expiration / time_to_live / expiration	Message lifetime in seconds (TTL — Time To Live). The message is not delivered after expiration. Set in account settings.
priority / urgency	Delivery priority: HIGH or NORMAL. Determines whether the device is woken up to receive the message.
_soundless / silent	Silent notification flag: true — sound disabled, false — default sound.
_vibration	Forced vibration flag (Android): true or false.
sound	Notification sound (iOS). Default: "default". Can contain a sound file name from the app.

Event tracking

Field	Description
_hub_link	JSON object with two encrypted URLs for delivery event tracking. Each URL is unique for a specific message and subscription.
_hub_link.open	URL to register the open event. Fires when the user taps the notification.
_hub_link.ack	URL to register the delivery event. Fires when the push service confirms delivery to the device.

Action buttons

Field	Description
_buttons	JSON array of action buttons. Each button contains label (button text) and link (URL opened on tap). Generated from buttons added in Altcraft Platform message settings.

Additional data

Field	Description
ak_uid	Additional field added to the data object alongside _uid. Contains the same SendMessageID. Used for compatibility with some SDKs.
category	Notification category (iOS). Always "Altcraft". Used to determine available actions on tap.
mutable-content	iOS flag. Always 1. Enables Content-Extension for notification modification (e.g., image download).

Differences between Legacy and v1 formats

Altcraft Platform supports two formats for sending via Firebase:

Legacy API (https://fcm.googleapis.com/fcm/send):

• Uses the deprecated FCM endpoint.
• Parameters are passed at the root level of the JSON object.
• Custom data is added to the data field at the top level.

API v1 (https://fcm.googleapis.com/v1/projects/{project_id}/messages:send):

• Modern FCM endpoint.
• Message structure is wrapped in a message object.
• Custom data is added to message.data.
• Uses JWT authentication instead of server key.
• Supports batch sending and multicast.

The current version of Altcraft Platform uses API v1 for all Firebase sends.

How to add custom data to the data object

Altcraft Platform supports adding user-defined fields to the data object of a push message. Custom data is set in message settings and merged with system fields.

Processing order:

1. Base custom data from push.CustomJSON (global for the message).
2. Platform-specific custom data from push.Android.CustomJSON or push.IOS.CustomJSON (overrides base data).
3. Altcraft system fields are added independently.

Example of custom data:

{
  "custom_field_1": "value1",
  "custom_field_2": 42,
  "custom_object": "{\"nested_key\": \"nested_value\"}"
}

note

Custom data is added to the data object alongside system fields. Field names should not conflict with system prefixes (_uid, _launch_id, _ac_push, etc.).

To add custom data, contact Altcraft Platform support.