<a id="push_token_reporter_webservice"></a>

# Push Token Reporter

## Overview

This web service can be used to report the Push Token to a server, together with other information like application id,
account username etc. Push Token is an identifier which can be used to send push notifications to the mobile device via
Apple Push Notification Service or Google Cloud Messaging service.

The token will be reported every time the app is newly started.

Push notifications are sent via Acrobits Push Notification Mediator (pnmediator) server. For instructions on how to send pushes, see [HTTP Push](../../server/push/http_push.md).

!!! note
    For best User Experience, we recommend to also implement the [Account Removal Reporter](account_removal_reporter.md), which can be used to delete reported push tokens
    of inactive accounts.

## Parameters

Parameter templates for Push Token Reporter can use any variables from [global](intro.md#global-params) and [account](intro.md#account-params)
scopes. There are also additional, service-specific parameters for this service:

<a id="push-token-selector"></a>

### `selector` { .reference-entry }

This parameter uniquely identifies the account. You will need to pass this parameter to pnmediator if you wish to
send a push notification which is account specific (for example, a notification about incoming message which comes
from this account). The value is a SHA1 hash with a suffix.

Example: `12869E0E6E553673C54F29105A0647204C416A2A:7C3A0D14`

### `pushToken` { .reference-entry }

This is the identifier needed by Apple and Google push notification services to deliver the push to the specific
device and app. The value of this parameter will be a base64 - encoded string of variable length.

### `pushTokenIncomingCall` { .reference-entry }

This is the identifier needed by Apple voip (pushkit) notification service to deliver the incoming call push to the specific device and app. The value of this parameter will be a base64 - encoded string of variable length.
As of iOS13 there are two push token/application ID pairs. One for delivering pushes for incoming calls and the other for delivering all other pushes. This is the one to use for incoming call pushes. The application ID to use along with this token is in `pushappid_incoming_call`.

### `pushTokenOther` { .reference-entry }

This is the identifier needed by Apple non-voip (remote-notification) notification service to deliver the push to the specific device and app. The value of this parameter will be a base64 - encoded string of variable length.
As of iOS13 there are two push token/application ID pairs. One for delivering pushes for incoming calls and the other for delivering all other pushes. This is the one to use for other pushes. It is alias to `pushToken`. The application ID to use along with this token is in `pushappid_other` or just `pushappid`.

### `pushappid` { .reference-entry }

This is the application ID to use along with the `pushToken`.

### `pushappid_incoming_call` { .reference-entry }

This is the application ID to use along with the `pushTokenIncomingCall`.

### `pushappid_other` { .reference-entry }

This is the application ID to use along with the `pushTokenOther`. It is the alias for `pushappid`.

## Configuration { #configuration }

The following [Account XML](../account/account.md) keys are relevant for Push Token Reporter configuration:

### `pushTokenReporterUrl` { .reference-entry }

Contains the URL, including URL scheme, of the web service, possibly also with query string.

Example (with query-string and both token/appid pairs):

```
https://example.com/token/?username=%account[username]%&selector=%selector%&token_calls=%pushTokenIncomingCall%&appid_calls=%pushappid_incoming_call%&token_msgs=%pushTokenOther%&appid_msgs=%pushappid_other%
```

Example (without query-string and with just non-incoming-call token/appid):

```
https://example.com/pushToken/%account[username]%/%selector%/%pushToken%&appid=%pushappid%
```

### `pushTokenReporterPostData` { .reference-entry }

If filled in, the app will use POST request to report the token.

Example (for application/x-www-form-urlencoded):

```
username=%account[username]%&selector=%selector%&token_calls=%pushTokenIncomingCall%&appid_calls=%pushappid_incoming_call%&token_msgs=%pushTokenOther%&appid_msgs=%pushappid_other%
```

Example (for application/json):

```json
{ "username" : "%account[username]%", "token_calls" : "%pushTokenIncomingCall%", "token_msgs" : "%pushTokenOther%", "selector" : "%selector%", "appId_calls": "%pushappid_incoming_call%", "appId_msgs" : "%pushappid_other%" }
```

### `pushTokenReporterContentType` { .reference-entry }

Specifies the value of Content-Type header to be sent in the request. If not specified, the app will default to
`application/x-www-form-urlencoded`

## Response

The response will be considered successful if the HTTP response code is 2xx. Any responses which have other
response code are silently ignored, but the request is considered as failed and the app will try to make the request
later again.

There are no response values expected, so the body of the response is not parsed or processed in any way.

!!! note
    On iOS, there is sometimes a delay getting the pushTokenOther which results in the web service being called with a null value for `pushTokenOther`.
    But provided the response of your web service is successful, the web service should be called a few moments later when the app does have
    the pushTokenOther.

!!! note
    For the response to be considered successful, it must be `2xx OK` HTTP response, and the body must match the content type.
    e.g. if the response has content type of `application/json`, it must have a body of at least `{}`.
    But the simplest way to return a successful response is just with `200 OK`, no content type header and no body.

## Examples

### GET method

request:

```http
GET /token/?username=johndow&password=12345678&selector=12869E0E6E553673C54F29105A0647204C416A2A:7C3A0D14&token_msgs=QVBBOTFiRzlhcVd2bW54bllCWldHOWh4dnRrZ3pUWFNvcGZpdWZ6bWM2dFAzS2J&appid_msgs=com.cloudsoftphone.app&token_calls=Udl99X2JFP1bWwS5gR%2FwGeLE1hmAB2CMpr1Ej0wxkrY%3D&appid_calls=com.cloudsoftphone.app.pushkit HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
```

response:

```http
HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Length: 0
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
```

### POST method, JSON

request:

```http
POST /token/johndow/ HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
Content-Type: application/json
Content-Length: 183

{
    "token_msgs"    : "QVBBOTFiRzlhcVd2bW54bllCWldHOWh4dnRrZ3pUWFNvcGZpdWZ6bWM2dFAzS2J",
    "appid_msgs"    : "com.cloudsoftphone.app",
    "token_calls"   : "Udl99X2JFP1bWwS5gR/wGeLE1hmAB2CMpr1Ej0wxkrY=",
    "appid_calls"   : "com.cloudsoftphone.app.pushkit",
    "selector"      : "12869E0E6E553673C54F29105A0647204C416A2A:7C3A0D14"
}
```

response:

```http
HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Length: 0
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
```