.. _push_token_reporter_webservice: Push Token Reporter =================== .. contents:: :local: :depth: 3 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 :ref:`http-push`. Parameters ---------- Parameter templates for Push Token Reporter can use any variables from :ref:`global-params` and :ref:`account-params` scopes. There are also additional, service-specific parameters for this service: .. _selector: ``selector`` ~~~~~~~~~~~~ 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`` ~~~~~~~~~~~~~ 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`` ~~~~~~~~~~~~~~~~~~~~~~~~~ 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`` ~~~~~~~~~~~~~~~~~~~~~~~~~ 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`` ~~~~~~~~~~~~~ This is the application ID to use along with the ``pushToken`` ``pushappid_incoming_call`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is the application ID to use along with the ``pushTokenIncomingCall`` ``pushappid_other`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is the application ID to use along with the ``pushTokenOther``. It is the alias for ``pushappid`` Configuration ------------- The following :ref:`account-xml` keys are relevant for Push Token Reporter configuration: ``pushTokenReporterUrl`` ~~~~~~~~~~~~~~~~~~~~~~~~ Contains the URL, including URL scheme, of the web service, possibly also with query string. Example (with query-string and both token/appid pairs): .. code-block:: none 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): .. code-block:: none https://example.com/pushToken/%account[username]%/%selector%/%pushToken%&appid=%pushappid% ``pushTokenReporterPostData`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If filled in, the app will use POST request to report the token Example ( for application/x-www-form-urlencoded): .. code-block:: none username=%account[username]%&selector=%selector%&token_calls=%pushTokenIncomingCall%&appid_calls=%pushappid_incoming_call%&token_msgs=%pushTokenOther%&appid_msgs=%pushappid_other% Example ( for application/json ): .. code-block:: json { "username" : "%account[username]%", "token_calls" : "%pushTokenIncomingCall%", "token_msgs" : "%pushTokenOther%", "selector" : "%selector%", "appId_calls": "%pushappid_incoming_call%", "appId_msgs" : "%pushappid_other%" } ``pushTokenReporterContentType`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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: .. code-block:: 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: .. code-block:: 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: .. code-block:: 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: .. code-block:: 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