README

ionic-push-php is a library that allows you to consume the Ionic Cloud API for sending push notifications (normal and scheduled), get a paginated list of sending push notifications, get information of registered devices, remove registered devices by token, ...

Ionic official documentation: Ionic HTTP API - Push.

Requirements:

PHP 5.1+
cURL

Installation:

composer require tomloprod/ionic-push-php

Configuration:

First, make sure you have your $ionicAPIToken and your $ionicProfile:

(string) $ionicAPIToken: The API token that you must create in Settings › API Keys in the Dashboard.
(string) $ionicProfile: The Security Profile tag found in Settings › Certificates in the Dashboard

More information here.

If you don't know how to configure your ionic app, you can take a look here: Setup Ionic Push

Exceptions

This library could throw:

RequestException

echo $e;
echo $e->prettify();
echo $e->getCode();
echo $e->getMessage();
echo $e->getType();
echo $e->getLink();

How to use:

First, instance an object as follow:

use Tomloprod\IonicApi\Push,
    Tomloprod\IonicApi\Exception\RequestException;

$ionicPushApi = new Push($ionicProfile, $ionicAPIToken);

Then you can interact (list, remove, create, ...) with device tokens, messages and notifications.

Remember that all the interactions returns an ApiResponse object instance, except notifications->deleteAll that returns an array of ApiResponses.

[Device Tokens]

1) List tokens:

try {

  $response = $ionicPushApi->deviceTokens->paginatedList([
      // Determines whether to include invalidated tokens (boolean)
      'show_invalid' => 1,
      // Only display tokens associated with the User ID (string)
      'user_id' => $desiredUserId,
      // Sets the number of items to return per page (integer)
      'page_size' => 4,
      // Sets the page number (integer)
      'page' => 1
  ]);

  foreach($response->data as $deviceToken){        
      print_r($deviceToken);
  }

} catch(RequestException $e) {
  echo $e;
}

2) List users associated with a device token:

try {

  $response = $ionicPushApi->deviceTokens->listAssociatedUsers($desiredDeviceToken, [
      // Sets the number of items to return per page (integer)
      'page_size' => 1,
      // Sets the page number (integer)
      'page' => 1,
  ]);

  // Do what you want with $response->data

} catch(RequestException $e) {
  echo $e;
}

3) Associate a user with a device token:

try {

  $deviceToken = "c686...";
  $userId = "a99ee...";
  $ionicPushApi->deviceTokens->associateUser($deviceToken, $userId);

  // The user has been associated.

} catch(RequestException $e) {
  echo $e;
}

4) Dissociate a user with a device token:

try {

  $deviceToken = "c686...";
  $userId = "a99ee...";
  $ionicPushApi->deviceTokens->dissociateUser($deviceToken, $userId);

  // The user has been dissociated.

} catch(RequestException $e) {
  echo $e;
}

5) Create device token that was previously generated by a device platform:

try {

  $response = $ionicPushApi->deviceTokens->create([
      // Device token (string)
      'token' => $newToken,
      // User ID. Associate the token with the User (string)
      'user_id' => $uuid
  ]);

  // Do what you want with $response->data

} catch(RequestException $e) {
  echo $e;
}

6) Retrieve device information related to the device token:

try {

  $response = $ionicPushApi->deviceTokens->retrieve($desiredDeviceToken);

  // Do what you want with $response->data

} catch(RequestException $e) {
  echo $e;
}

5) Update an specific token:

try {

  $isValid = true; // Determines whether the device token is valid (boolean)
  $ionicPushApi->deviceTokens->update($desiredDeviceToken, ['valid' => $isValid]);

  // The device token has been updated.

} catch(RequestException $e) {
  echo $e;
}

6) Delete a device related to the device token:

try {

  $ionicPushApi->deviceTokens->delete($desiredDeviceToken);

  // The device token has been deleted.

} catch(RequestException $e) {
  echo $e;
}

[Messages]

1) Retrieve specific message:

try {
  $response = $ionicPushApi->messages->retrieve($desiredMessageId);

  // Do what you want with $response->data

} catch(RequestException $e) {
  echo $e;
}

2) Delete a message:

try {
  $ionicPushApi->messages->delete($desiredMessageId);

  // The message has been deleted.

} catch(RequestException $e) {
  echo $e;
}

[Notifications]

1) List notifications:

try {

  $response = $ionicPushApi->notifications->paginatedList([
      // Sets the number of items to return per page (integer)
      'page_size' => 1,
      // Sets the page number (integer)
      'page' => 1,
      // You can also pass other fields like "message_total" or "overview" (string[])
      'fields' => [
          // Total number of messages tied to each notification.
          'message_total',
          // Get an overview of messages delivered and failed for each notification.
          'overview'
      ]
  ]);

  // Do what you want with $response->data

} catch(RequestException $e) {
  echo $e;
}

2) Retrieve specific notification:

try {

  $response = $ionicPushApi->notifications->retrieve($desiredNotificationId);

  // Do what you want with $response->data

} catch(RequestException $e) {
  echo $e;
}

3) Delete a notification:

try {
  $ionicPushApi->notifications->delete($desiredNotificationId);

  // Notification has been deleted.

} catch(RequestException $e) {
  echo $e;
}

4) Delete all notifications:

try {
?
  $responses = $ionicPushApi->notifications->deleteAll();

  // Notifications have been deleted.

} catch(RequestException $e) {
  echo $e;
}

5) List messages of a notification:

try {

  $response = $ionicPushApi->notifications->listMessages($desiredNotificationId, [
      // Sets the number of items to return per page (integer)
      'page_size' => 1,
      // Sets the page number (integer)
      'page' => 1
  ])

  // Do what you want with $response->data

} catch(RequestException $e) {
  echo $e;
}

6) Send notifications:

/**
* ANDROID [OPTIONAL] CONFIG PARAMETERS
*/

// Filename of the Icon to display with the notification (string)
$icon = "icon";

// Filename or URI of an image file to display with the notification (string)
$image = "image";

// Indicates whether each notification message results in a new entry on the notification center on Android.
// If not set, each request creates a new notification.
// If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.
$tag = "yourTagIfYouNeedIt";

// When this parameter is set to true, it indicates that the message should not be sent until the device becomes active. (boolean)
$delayWhileIdle = false;

// Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed. (string)
$collapseKey = "group1";


/**
* IOS [OPTIONAL] CONFIG PARAMETERS
*/

// Message Priority. A value of 10 will cause APNS to attempt immediate delivery.
// A value of 5 will attempt a delivery which is convenient for battery life. (integer)
$priority = 10;

// The number to display as the badge of the app icon (integer)
$badge = 1;

// Alert Title, only applicable for iWatch devices
$iWatchTitle = "Hi!";


// Assign the previously defined configuration parameters to each platform, as well as the title and message:
$notificationConfig = [
    'title' => 'Your notification title',
    'message' => 'Your notification message. Bla, bla, bla, bla.',
    'android' => [
        'tag' => $tag,
        'icon' => $icon,
        'image' => $image,
        'delay_while_idle' => $delayWhileIdle,
        'collapse_key' => $collapseKey
    ],
    'ios' => [
        'priority' => $priority,
        'badge' => $badge,
        'title' => $iWatchTitle
    ]
];

// [OPTIONAL] You can also pass custom data to the notification. Default => []
$notificationPayload = [
    'myCustomField' => 'This is the content of my customField',
    'anotherCustomField' => 'More custom content'
];

// [OPTIONAL] And define, if you need it, a silent notification. Default => false
$silent = true;

// [OPTIONAL] Or/and even a scheduled notification for an indicated datetime. Default => ''
$scheduled = '2016-12-10 10:30:10';

// [OPTIONAL] Filename of audio file to play when a notification is received. Setting this to default will use the default device notification sound. Default => 'default'
$sound = 'default';

// Configure notification:
$ionicPushApi->notifications->setConfig($notificationConfig, $notificationPayload, $silent, $scheduled, $sound);

try {

  // Send notification...
  $response = $ionicPushApi->notifications->sendNotificationToAll(); // ...to all registered devices
  // or
  $response = $ionicPushApi->notifications->sendNotification([$desiredToken1, $desiredToken2, $desiredToken3]); // ...to some devices

  // Do what you want with $response->data

} catch(RequestException $e) {
  echo $e;
}

7) Replace existing notification with new config:

// Identifier of the notification we want to replace.
$notificationToReplace = "a86feewx...";

/**
* ANDROID [OPTIONAL] CONFIG PARAMETERS
*/

// Filename of the Icon to display with the new notification (string)
$icon = "icon";

// Filename or URI of an image file to display with the new notification (string)
$image = "image";

// Indicates whether each notification message results in a new entry on the notification center on Android.
// If not set, each request creates a new notification.
// If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.
$tag = "yourTagIfYouNeedIt";

// When this parameter is set to true, it indicates that the message should not be sent until the device becomes active. (boolean)
$delayWhileIdle = false;

// Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed. (string)
$collapseKey = "group1";


/**
* IOS [OPTIONAL] CONFIG PARAMETERS
*/

// Message Priority. A value of 10 will cause APNS to attempt immediate delivery.
// A value of 5 will attempt a delivery which is convenient for battery life. (integer)
$priority = 10;

// The number to display as the badge of the app icon (integer)
$badge = 1;

// Alert Title, only applicable for iWatch devices
$iWatchTitle = "Hi!";


// Assign the previously defined configuration parameters to each platform, as well as the title and message:
$notificationConfig = [
    'title' => 'Your notification title',
    'message' => 'Your notification message. Bla, bla, bla, bla.',
    'android' => [
        'tag' => $tag,
        'icon' => $icon,
        'image' => $image,
        'delay_while_idle' => $delayWhileIdle,
        'collapse_key' => $collapseKey
    ],
    'ios' => [
        'priority' => $priority,
        'badge' => $badge,
        'title' => $iWatchTitle
    ]
];

// [OPTIONAL] You can also pass custom data to the new notification. Default => []
$notificationPayload = [
    'myCustomField' => 'This is the content of my customField',
    'anotherCustomField' => 'More custom content'
];

// [OPTIONAL] And define, if you need it, a silent notification. Default => false
$silent = true;

// [OPTIONAL] Or/and even a scheduled notification for an indicated datetime. Default => ''
$scheduled = '2016-12-10 10:30:10';

// [OPTIONAL] Filename of audio file to play when a notification is received. Setting this to default will use the default device notification sound. Default => 'default'
$sound = 'default';

// Configure new notification:
$ionicPushApi->notifications->setConfig($notificationConfig, $notificationPayload, $silent, $scheduled, $sound);

try {

  // Replace notification with new configuration
  $response = $ionicPushApi->notifications->replace($notificationToReplace);

  // Do what you want with $response->data

} catch(RequestException $e) {
  echo $e;
}

Contributing:

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -m 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

tomloprod / ionic-push-php

Maintainers

Details