Processing and adding a subscription
Once the app received a push token, the app must transfer it to Altcraft Platform in order to create a subscription. The API request is used for it.
With this request, you can:
- Add new subscriptions.
- Change the status of existing subscriptions.
The profile search mode can be set using the matching field in the request (see specification below). If the profile is not found, a new one will be created.
Moreover, if several databases are specified in the resource, then all of them will be processed separately. A request to such a resource will create and update profiles in several databases at once. An example of such a case can be seen below.
If there are no databases in the resource, then an error will be returned.
URL
Method: POST
https://<cookiesaver_host>/push_subscribe
Request parameters
| Parameter | Type | Example | Required | Description |
|---|---|---|---|---|
| id | string | "abcdefghijklmnqrstuvwxyz" | No | Profile ID |
| resource_token | string | "abcdefghijklmnqrstuvwxyz" | Yes | Unique resource ID |
| db_ids | [ ] int | [ 2,3 ] | No | Resource database filter. |
| matching | string | "custom" | No | Profile search mode. If the parameter is not passed or is empty, profile search by ID will be used. If ID is also not passed, search by push subscriptions will be used. For the push_subscribe method, this parameter can only accept the following values:
|
| subscriptions | JSON array SubscriptionObject | [{ | Yes | Push subscriptions that should be added to profile or should be updated. "subscription_id" is unique for each device. |
SubscriptionObject
| Parameter | Type | Example | Required | Description |
|---|---|---|---|---|
| provider | string | "android-firebase" | Yes | Altcraft Platform Provider ID. The available values:
Each token type in AppMetrica has its own provider ID. |
| subscription_id | string | "abcdef-ghijklmn-qrstuvwxyz" | Yes | Subscription push token |
| unsubscribe | bool | false | No | Unsubscribe flag. Dismisses subscription if true. |
Response parameters
| Parameter | Type | Description |
|---|---|---|
| data | JSON array DataObject | Information about the created subscriptions. The array can contain several objects in the following cases:
|
| error | int | Error code |
| error_text | string | Error text |
DataObject
| Parameter | Type | Description | |
|---|---|---|---|
| subscription_id | string | "abcdef-ghijklmn-qrstuvwxyz" | Subscription push token |
| unsubscribe | bool | false | Flag whether the subscription was added or canceled |
| profile_id | string | "5fb62e815ae47a4aa04dfadd" | ID of the profile (transferred or newly created) for which the subscription was added. |
| provider | string | "android-firebase" | Altcraft Platform Provider ID. The available values:
Each token type in AppMetrica has its own provider ID. |
| db_id | int | 2 | Altcraft Platform Database ID. The profile is stored in this database. |
| resource_id | int | 1 | Altcraft Platform resource ID. |
| subscription_hash_id | string | "92807e89" | Subscription hash |
| status | string | "error" | Operation status
|
| description | string | "Duplicate push subscription" | Error description |
File import
Push tokens can be imported not only via API, but also from a CSV file through the platform interface. This method is convenient when you need to bulk-add already collected tokens without modifying the mobile app or server integration.
When importing, you specify the push notification provider, for example android-firebase, ios-apns, or another supported provider. The uploaded tokens will be added as push subscriptions to profiles.
Before importing, prepare a CSV file with data for profile matching and subscription tokens. Profiles can be matched by available identifiers, such as system profile ID or an additional field.
Before importing, verify that the required databases are configured in the resource and the correct subscription provider is selected. If a token is submitted with an incorrect provider, push notifications for that subscription will not be delivered correctly.
Examples
Request with matching by system profile ID
Request
{
"id": "59db33d269d426509e9c4bf9",
"resource_token": "3LXP2FRcRxJ-7b14db88ec937f14",
"subscriptions": [
{
"provider": "android-firebase",
"subscription_id": "%subscriptionid%"
}
]
}
Response
{
"data": [
{
"subscription_id": "%subscriptionid%",
"unsubscribe": false,
"profile_id": "59db33d269d426509e9c4bf9",
"provider": "android-firebase",
"db_id": 17,
"resource_id": 5,
"subscription_hash_id": "adsfdfdffdf",
"status": "ok",
"description": ""
}
],
"error": 0,
"error_text": "Successful operation"
}
Request with matching by a custom profile field
Request
{
"resource_token": "3LXP2FRcRxJ-7b14db88ec937f14",
"matching": "custom",
"field_name": "CustomNumber1",
"field_value": 123,
"subscriptions": [
{
"provider": "android-firebase",
"subscription_id": "%subscriptionid%"
}
]
}
Response
{
"data": [
{
"subscription_id": "%subscriptionid%",
"unsubscribe": false,
"profile_id": "59db33d269d426509e9c4bfс",
"provider": "android-firebase",
"db_id": 17,
"resource_id": 5,
"subscription_hash_id": "adsfdfdffdf",
"status": "ok",
"description": ""
}
],
"error": 0,
"error_text": "Successful operation"
}
Request with matching by push subscriptions
Request
{
"resource_token": "3LXP2FRcRxJ-7b14db88ec937f14",
"subscriptions": [
{
"provider": "android-firebase",
"subscription_id": "%subscriptionid%"
}
]
}
Response
{
"data": [
{
"subscription_id": "%subscriptionid%",
"unsubscribe": false,
"profile_id": "59db33d269d426509e9c4bfa",
"provider": "android-firebase",
"db_id": 17,
"resource_id": 5,
"subscription_hash_id": "adsfdfdffdf",
"status": "ok",
"description": ""
}
],
"error": 0,
"error_text": "Successful operation"
}
Request to a resource with several databases
Request
{
"resource_token": "3LXP2FRcRxJ-7b14db88ec937f14",
"matching": "custom",
"field_name": "CustomNumber1",
"field_value": 12345,
"subscriptions": [
{
"provider": "android-firebase",
"subscription_id": "%subscriptionid%"
}
]
}
Response
{
"error": 200,
"error_text": "Successful operation",
"data": [
{
"db_id": 34,
"description": "",
"profile_id": "6156ed18eb7fec10a206e916",
"provider": "android-firebase",
"resource_id": 22,
"status": "ok",
"subscription_hash_id": "340ca49c",
"subscription_id": "%subscriptionid%",
"unsubscribe": false
},
{
"db_id": 2,
"description": "matching error: unknown field",
"resource_id": 22,
"status": "error"
}
]
}
Request with matching by a custom profile field in a certain database
Request
{
"resource_token": "3LXP2FRcRxJ-7b14db88ec937f14",
"db_ids": [1],
"matching": "custom",
"field_name": "CustomNumber1",
"field_value": 123,
"subscriptions": [
{
"provider": "android-firebase",
"subscription_id": "%subscriptionid%"
}
]
}
Response
{
"error": 0,
"error_text": "Successful operation",
"data": [
{
"db_id": 1,
"description": "",
"profile_id": "637f1a284fda7c5c08be62f",
"provider": "android-firebase",
"resource_id": 31,
"status": "ok",
"subscription_hash_id": "f8af057de",
"subscription_id": "%subscriptionid%",
"unsubscribe": false
}
]
}
Request did not update or add any profile subscriptions
Request
{
"resource_token": "3LXP2FRcRxJ-7b14db88ec937f14",
"matching": "custom",
"field_name": "CustomNumber1",
"field_value": 12345,
"subscriptions": [
{
"provider": "android-firebase",
"subscription_id": "%subscriptionid%"
}
]
}
Response
{
"error": 200,
"error_text": "Successful operation",
"data": [
{
"db_id": 34,
"description": "",
"profile_id": "6156ed18eb7fec10a206e916",
"resource_id": 22,
"status": "ok"
}
]
}