README

Tify

Unified push notification services abstraction layer to connect with Google GCM and Apple APNS services.

Installation

Install using Composer:

composer require juliangut/tify

Then require_once the autoload file:

require_once './vendor/autoload.php';

Concepts

Receiver

Each of the individual devices that will receive push notification. Identified by a device token provided by push notification service (APNS or GCM).

new \Jgut\Tify\Receiver\ApnsReceiver('device_token');
new \Jgut\Tify\Receiver\GcmReceiver('device_token');

device_token follow different formats depending on service type. Review APNS and GCM documentation for proper formatting.

Message

Messages compose the final information arriving to receivers. GCM and APNS messages hold different information according to each service specification.

In order for the message payload to be created one of the following message parameters must be present:

For APNS
- title
- title_loc_key
- body
- loc_key
For GCM
- title
- title_loc_key
- body
- body_loc_key

Messages can hold any number of custom payload data that will compose additional data sent to the destination receivers.

This key/value payload data must comply with some limitations to be fully compatible with different services at once, for this a prefix (data_ by default) is automatically added to the key. This prefix can be changed or removed if needed, but be aware that payload data should not be a reserved word (aps, from or any word starting with google or gcm) or any GCM notification parameters.

Find APNS message parameters here in table 3-2.

Find GCM message parameters here in table 2.

Notification

It's a container to keep a message and its associated destination receivers.

Notifications are the central unit of work, several notifications can be set into a Tify Service sharing the same adapters but sending different messages to different receivers.

Notifications hold some extra parameters used by the push notification services to control behaviour and/or be used in notification creation.

By clearing receivers list or changing message a notification can be reused as many times as needed.

Find APNS notification parameters here in table 3-1.

Find GCM notification parameters here in table 1.

Adapter

Adapters will be given notifications to actually send the messages to associated receivers using the corresponding notification service. Receivers will be automatically filtered for the correct service by their type.

For APNS adapter certificate parameter is mandatory, denoting the path to the service certificate (.pem file). In GCM api_key is the mandatory parameter denoting Google API key.

$apnsService = new \Jgut\Tify\Service\ApnsService(['certificate' => 'path_to_certificate.pem']);
$gcmService = new \Jgut\Tify\Service\GcmService(['api_key' => 'google_api_key']);

Result

Responses from APNS and GCM push services are very different from one another, Result is a response abstraction in order to provide a common interface to access this non-equal returning data from APNS and GCM services.

This objects are composed of device token, date, status code (a status categorization) and status message (which corresponds to the original APNS or GCM response status).

Status Codes

STATUS_SUCCESS, push was successful
STATUS_INVALID_DEVICE, device token provided is invalid
STATUS_INVALID_MESSAGE, message was not properly composed
STATUS_RATE_ERROR, only for GCM
STATUS_AUTH_ERROR, only for GCM
STATUS_SERVER_ERROR
STATUS_UNKNOWN_ERROR

Among all the result statuses, STATUS_INVALID_DEVICE is the most interesting because it is a signal that you should probably remove that token from your database.

Service

For simplicity instead of handing notifications to adapters one by one 'Tify Service' can be used to send Notifications to its corresponding receivers using correct provided Adapters, automatically merging notification Results into a single returned array.

Usage

Push

Basic usage creating a one message to be sent through different adapters.

use Jgut\Tify\Adapter\Apns\ApnsAdapter;
use Jgut\Tify\Adapter\Gcm\GcmAdapter;
use Jgut\Tify\Message;
use Jgut\Tify\Notification;
use Jgut\Tify\Receiver\ApnsReceiver;
use Jgut\Tify\Receiver\GcmReceiver;
use Jgut\Tify\Service;

$adapters = [
    new GcmAdapter(['api_key' => '00000']),
    new ApnsAdapter(['certificate' => 'path_to_certificate']),
];

$message = new Message([
    'title' => 'title',
    'body' => 'body',
]);

$receivers = [
    new GcmReceiver('aaaaaaaaaaa'),
    new GcmReceiver('bbbbbbbbbbb'),
    new ApnsReceiver('ccccccccccc'),
    new ApnsReceiver('ddddddddddd'),
];

$service = new Service($adapters, new Notification($message, $receivers));

$results = $service->push();

Sharing the same adapters to send different messages

use Jgut\Tify\Adapter\Gcm\GcmAdapter;
use Jgut\Tify\Message;
use Jgut\Tify\Notification;
use Jgut\Tify\Receiver\GcmReceiver;
use Jgut\Tify\Service;

$adapters = [
    new GcmAdapter(['api_key' => '00000']),
    new GcmAdapter(['api_key' => '11111']),
];

$service = new Service($adapters);

$service->addNotification(new Notification(
    new Message([
        'title' => 'title_one',
        'body' => 'body_one',
    ]),
    [
        new GcmReceiver('aaaaaaaaaaa'),
        new GcmReceiver('bbbbbbbbbbb'),
    ]
));

$service->addNotification(new Notification(
    new Message([
        'title' => 'title_two',
        'body' => 'body_two',
    ]),
    [
        new GcmReceiver('xxxxxxxxxxx'),
        new GcmReceiver('zzzzzzzzzzz'),
    ]
));

$results = $service->push();

Feedback

use Jgut\Tify\Adapter\Gcm\ApnsAdapter;
use Jgut\Tify\Service;

$adapters = [
    new ApnsAdapter(['certificate' => 'path_to_certificate_one']),
    new ApnsAdapter(['certificate' => 'path_to_certificate_two']),
];

$service = new Service($adapters);

$results = $service->feedback();

Feedback returns Result objects with token and time of expired device tokens.

Contributing

Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before.

See file CONTRIBUTING.md

License

See file LICENSE included with the source code for a copy of the license terms.

juliangut / tify

Maintainers

Details