Prerequisite knowledge
 
  • Basic understanding of PHP and hosting server.
User level: All
 
Required Adobe products (retail)
 
Additional required other products (third-party/labs/open source)
 
Sample files
 
By downloading software from the Adobe website you agree to the terms of our license agreement. Please read it before downloading.
 

 
Introduction

Using the push notification API, you can send push notifications in a programmatic way to Apps built with Adobe DPS.
 
This article gives an overview of the examples of this API. Each of the PHP snippets generates a request to one of the many Push functionalities available through the push notification API. When you finish reading this article, you will be able to understand how to make the API requests and the formats of their respective parameters.
 
Please note that the current version of the push notification API only supports iOS.
 

 
Downloading Push Notification API Snippets

Please download dps-push-notification-php-snippets.zip. Extract the file into the default folder named dps-push-notification-php-snippets. Please select a location for this folder that can be easily found, as it will be utilized throughout this article. This folder contains all the code snippets that are necessary to interact with the push notification API. 
 

 
Requesting IMS Client ID and Secret

Every software-client that wants to consume the Adobe Push Notification API has to request an API Key (also known as IMS client ID), with corresponding secret.
 
API Key/IMS Client ID
 
  1. Download the DPS Push Notifications API Request Form and fill it out.
  2. Submit the PDF form to the Adobe World Wide Developer Support (wwds@adobe.com).
  3. Wait after the IMS client ID and secret has been whitelisted by the Adobe WWDS before continuing.

 
Requesting a DPS Account

The Digital Publishing Suite account used in this article will require an application role. Please read this article to know how you can assign an application role to a DPS account.
 

 
Creating Push Certificates

The Push Notification service requires a valid Sandbox (aka Development) and Production certificates with Push enabled. Please follow this guide to create the iOS Push certificates. Please move the two .p12 certificates (development and distribution) into the folder call certificate within the root directory of the dps-push-notification-php-snippets folder, and rename the developer and distribution .p12 certificates into aps_development_bootcamp.p12 and aps_production_bootcamp.p12, respectively.
 

 
Updating Push Notification API Parameters

The PHP snippet utilizes three files that store the login and API parameters: credentials.php, endpoints.php, and parameters.php. The files are located within the config folder from the root directory of the dps-push-notification-php-snippets folder.
 
All parameters are currently commented out in the mentioned three files. Please uncomment each parameters before use by deleting the double backslash (“//”) in front of each parameter. To enter the desired value for a parameter, please enter it within the single quotes next to the parameter’s name.
 

 
Credentials

  1. Open the file credentials.php with a text editor.
  2. Enter the IMS client ID next to the field $ims_client_id (line 18). The IMS client ID must be whitelisted by Adobe WWDS.
  3. Enter the IMS client secret next to the field $ims_client_secret (line 21).
  4. Enter the DPS account username next to the field $dps_username (line 28). The DPS account must have an application role.
  5. Enter the DPS account password next to the field $dps_password (line 31).
  6. (Optional) Enter the IMS client access token next to the field $ims_access_token (line 25)
    • Only enter this value during development stage.
    • Each HTTPS request to the push notification server will require the IMS access token. By having this field entered, the PHP snippet will skip the HTTPS request to the IMS server for the access token. This will result in faster request time.
    • The IMS access (user) token will last for 48 hours.

 
API Endpoints

  1. Only continue if the URL to the IMS server and the push notification server have changed. Otherwise, skip the steps below.
  2. Open the file endpoints.php with a text editor.
  3. Enter the IMS server URL next to the field $ims_server_endpoint (line 18).
  4. Enter the push notification server URL next to the field $notification_endpoint (line 21).

 
API Parameters

  1. Open the file parameters.php with a text editor.
  2. This file contains all the push notification API parameters.
  3. Enter the IMS scope next to the field $ims_scope (line 27)
    • The IMS scope is the IMS server parameter.
    • The default value should be “openid,sao.digital_publishing”
  4. Enter a particular push notification ID next to the field $notification_id (line 40)
    • The push notification ID is used for the process of getting the push notification status and stopping the push notification.
    • The push notification ID can be found by one of the following ways:
    • After successfully sending the push notification (send_notification.php), it will output the push notification ID.
    • Get a list of push notifications (get_notification_history.php) to see their respective push notification ID.
  5. Enter the issue ID next to the field $issue_id (line 52)
    • The issue ID is used for querying a list of articles within an issue (folio).
    • The issue ID can be found by requesting for the list of issues (get_issue_list.php).
  6. Enter the issue version next to the field $issue_version (line 65)
    • The issue version is used for querying the list of articles by the issue version.
    • The issue version is currently not used, but it is still required by the push notification API.
  7. (Optional) Enter the start date next to the field $history_from_date (line 78)
    • The start date is to filter the list of notifications from that date.
    • If the start date is not provided, the list will start from the first notification.
    • The date must be in one of the two formats:
      • mm/dd/yyyy
      • mm/dd/yyyy hh:mm:ss
  8. (Optional) Enter the end date next to the field $history_to_date (line 91)
    • The end date is to filter the list of notifications to that date.
    • If the start date is not provided, the list will end at the last notification.
    • The date must be in one of the two formats:
      • mm/dd/yyyy
      • mm/dd/yyyy hh:mm:ss
  9. (Optional) Enter the device file path next to the field $deviceFile (line 103):
    • The device file is a CSV file with a list of push notification tokens (unique per device) to send the push notification to.
  10. Enter the push schedule date next to the field $push_schedule (line 117):
    • The schedule date is for when to send the push notification.
    • The date must be in one of the two formats:
      • mm/dd/yyyy
      • mm/dd/yyyy hh:mm:ss
  11. (Optional) Enter the list of push devices next to the field $push_devices (line 131):
    • The push device is a string of push notification tokens (unique per device), separated by commas.
    • This is similar to $deviceFile; an alternative way to easily target a small number of devices.
    • If $push_devices is set, you do not need to set $deviceFile as well.
  12. (Optional) Enter the push message next to the field $push_message (line 145):
    • The push message is the text to send with the push notification.
    • If the push message is provided, the push notification will be a text-only notification.
  13. (Optional) Enter the push issue ID for Background Download next to the field $push_issueIdForBackgroundDownload (line 158).
  14. Enter the push sound ID next to the field $push_soundId (line 170).
  15. Specify whether to show the badge next to the field $push_badge (line 182).
  16. Specify whether to send push notification for Production or Sandbox next to the field $push_isProduction (line 194).
  17. (Optional) Enter the segment of devices to send the push notification to next to the field $push_segmentDef (line 207).
  18. (Optional) Enter the name of the issue (folio) to deep link for the push notification next to the field $push_issueName (line 219)
  19. (Optional) Enter the name of the article to deep link for the push notification next to the field $push_articleName (line 231).
  20. (Optional) Enter the application ID next to the field $push_applicationId (line 243).
  21. (Optional) Enter the background message next to the field $push_backgroundMessage (line 255).
  22. Enter the push notification reminder next to the field $push_remindInHours (line 267).
  23. Enter the certificate type next to the field $certificate_type (line 280).
  24. Enter the certificate ID next to the field $certificate_id (line 293).
  25. Enter the iOS bundle ID next to the field $iOS_bundle_id (line 306).
  26. Enter the iOS production certificate file path next to the field $iOS_production_certificate_filepath (line 320).
  27. Enter the iOS production certificate password next to the field $iOS_production_certificate_password (line 333).
  28. Enter the iOS sandbox certificate file path next to the field $iOS_sandbox_certificate_filepath (line 347).
  29.  Enter the iOS sandbox certificate password next to the field $iOS_sandbox_certificate_password (line 360).

 
Hosting the PHP Snippets

Please upload all the contents within the dps-push-notification-php-snippets folder to a hosting server. Since the PHP snippets utilizes PHP, the hosting server must have PHP installed.
 

 
Local Development

  1. The hosting server does not have to be an actual website.
  2. For local development purposes:
    • For Mac, please use MAMP
    • For Windows, please use MAMP or WAMP

 
Loading the PHP Snippets

Each of the PHP files contains a HTTPS request to the push notification API server, and will output the results of that API request. Please load the PHP files from the hosting server to make the HTTPS request.
 

 
Load the PHP Snippets

  1. From a web browser, navigate to the PHP file on the hosting server.
  2. The URL will have the following structure:
    • http://[server_name]/[php_snippets_folder]/[api_folders_name]/[php_snippet_file].php
  3. If the hosting server is localhost (via MAMP), then the URL to the get_ims_user_token.php file will be one of the following, depending on the MAMP configuration:

 
Locating the PHP Snippets WRT the API

The folders mentioned below are within the dps-push-notification-push-snippets folder. It is not necessary to make any modifications to the PHP snippets mentioned below, they will operate as configured.
 

 
IMS API

  1. The parameters for the IMS API are located within the credentials.php file, in the config folder.
  2. The PHP snippets related to the IMS API are located in the authorization folder. To get the IMS user token, load get_ims_user_token.php

 
Notification API

  1. The parameters for the push notification API are located within the parameters.php file, in the config folder.
  2. The PHP snippets related to the push notification API are located in the notification folder:
    1. To check the push notification’s status, load check_notification_availability.php
    2. To get the push notification’s history, please load get_notification_history.php
    3. To get the the status of a particular push notification, load get_notification_status.php
    4. To send a push notification, load send_notification.php
    5. To stop a push notification, load stop_notification.php
    6. To get a list of issues (folios) for a DPS account, load get_issue_list.php
    7. To get a list of articles within an issue (folio), load get_article_list.php

 
Certificate API

  1. The parameters for the push certificate API are located within the parameters.php file, in the config folder.
  2. The PHP snippets related to the push certificate API server are located in the certificate folder:
    • To get a list of available push certificates for a DPS account, load get_bundle_info.php
    • To get information about a particular push certificate, load get_certificate_info.php
    • To upload a set of push certificates (Production and Sandbox), load upload_ios_certificate.php

 
Where to go from here

For more information about the individual Push Notification API, please refer to this PDF.
 
Comments are currently closed as we migrate to a new commenting system. In the interim, please provide any feedback using our feedback form. Thank you for your patience.