reliefapps/notification-bundle

A Bundle providing services to send push notifications

, _(*1)

Installation

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:, _(*2)

$ composer require reliefapps/notification-bundle "0.1.4"

NB: Before version 1, backward compatibility may be broken. It is advised to force a single version of the bundle has shown here, _(*3)

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation., _(*4)

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the app/AppKernel.php file of your project:, _(*5)

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...

            new Reliefapps\NotificationBundle\ReliefappsNotificationBundle(),
        );

        // ...
    }

    // ...
}

Step 3 : Configure the Bundle

In your project, add at the end of the file app/config/config.yml the following configuration :, _(*6)

reliefapps_notification:
    android:
        server_key: **your_gcm_key**
    ios:
        push_certificate: **path_to_your_ios_certificate**
        push_passphrase: **your_passphrase_for_the_certificate**
        protocol: legacy

Optional (but recommended) :, _(*7)

For improved error management for iOS notifications, you will need http2 support for cURL on your machine. See this tutorial., _(*8)

Once you have followed this tutorial, check that cURL supports HTTP/2 by running :, _(*9)

$ curl --http2 -I https://nghttp2.org/

If it works, you can remove the line :, _(*10)

            protocol: legacy

in your app/config/config.yml file., _(*11)

Usage

Step 1: Create a Device Entity

First you will need to create you own Device Entity extending this Bundle's ReliefappsNotificationBundle:Device entity., _(*12)

Then complete your app/config/config.yml file with :, _(*13)

reliefapps_notification:
    #...
    device:
        class: YourBundle\Entity\Device

Step 2: Register some devices

In a strategic api controller (login, homepage), register the device UUID and token :, _(*14)

<?php

// ...
class YourController
{
    // ...
    public function YourAction()
    {
        // ...
        // Get the Device Manager
        $deviceManager = $this->get('reliefapps_notification.device.manager');

        // Create a new device
        $newDevice = $deviceManager->createDevice($uuid, $platform);
        $newDevice->setToken($token);

        // Save the device in database
        $deviceManager->udpateDevice($newDevice);

    }
}

Step 3: Create a notification Body

The class NotificationBody allows you to create the content of a push notification., _(*15)

<?php

use Reliefapps\NotificationBundle\Resources\Model\NotificationBody;

// ...
class YourController
{
    // ...
    public function YourAction()
    {
        // ...
        $body = new NotificationBody();
        $body ->setTitle('Notification Title')      // Title of the notification
              ->setBody('This is a notification !') // Text of the notification
              ->setBadge(42);                       // Badge on the app icon (iOS only)
    }
}

Step 4: Send a push notification

You are ready to send your first Push Notification !, _(*16)

The function sendPush takes an array of devices and a notification body, and sends the Push notifications to the devices !, _(*17)

If a token is invalid, it will be set to null on your database automatically., _(*18)

<?php

// ...
class YourController
{
    // ...
    public function YourAction()
    {
        // ...
        // Get the Push Manager
        $pushManager = $this->container->get('reliefapps_notification.push_manager');

        // Send a push notification to devices $device1 and $device2
        $pushManager->sendPush(Array($device1, $device2), $body);
    }
}

Advanced Configuration

Contexts

The configuration presented above does not allow you to switch servers (to switch between dev and prod) or to change apns_topic and certificates (to manage multiple applications from a single backend)., _(*19)

To solve this issue, we introduced the Object Context. A context is a set of configurations that can be used independently., _(*20)

Contexts are defined in your app/config/config.yml:, _(*21)

reliefapps_notification:
    android:
        server_key: **prod_gcm_key**
    ios:
        push_certificate: **prod_ios_certificate**
        push_passphrase: **prod_passphrase**
        apns_topic: myapp_prod
    contexts:
        ctx_dev:
            android:
                server_key: **dev_gcm_key**
                gcm_server: android.development.googleapis.com
            ios:
                push_certificate: **dev_ios_certificate**
                push_passphrase: **dev_passphrase**
                apns_server: api.development.push.apple.com
                apns_topic: myapp_dev
        ctx_app2:
            ios:
                apns_topic: myapp2

All fields that are not filled in the context will be filled with the default configuration., _(*22)

You can call the context by its name with the PushManager., _(*23)

For more info, lookup Reliefapps\NotificationBundle\Resources\Utils\ContextManager and Reliefapps\NotificationBundle\Resources\Model\Context., _(*24)

<?php

// ...
class YourController
{
    // ...
    public function YourAction()
    {
        // ...

        // The third parameter ("default" by default) indicates the context
        $pushManager->sendPush(Array($device1, $device2), $body, 'ctx_app2');
    }
}

Additional fields

You may want to add some data to the notification wanted to be sent., _(*25)

<?php

// ...
class YourController
{
    // ...
    public function YourAction()
    {
        // ...

        $additionalFields = array(
            array("key" => "id_user", "value" => 42),
            array("key" => "linkToFollow", "value" => "https://packagist.org/packages/reliefapps/notification-bundle")
        );

        $body->setAdditionalFields($additionalFields);
        $body->addAdditionalField(array("key" => "isNew", "value" => true));

        $pushManager->sendPush(Array($device1, $device2), $body);
    }
}

Documentation

Payloads

Entity : Reliefapps\NotificationBundle\Resources\Model\NotificationBody, _(*26)

Android Action

Entity : Reliefapps\NotificationBundle\Resources\Model\AndroidAction, _(*27)

, _(*28)