jBackend for Joomla 3.0

jBackend for Joomla 3.0 (24)

jBackend for Joomla 3.0

The Release System Module is implemented with the plg_jbackend_release plugin. It provides functions to implement a full Joomla Update Server and/or a generic Package Distribution System based on Joomla. It supports both free and paid packages, and it is seamlessly integrated with Joomla user's groups for authorization and license key generation. Here is the list of supported methods.

Generate key by email

Sends an email to the user with the license key for the specified package group.

Request parameters

action=post
module=release
resource=keybyemail
id=<package group>
email=<user email>

Example

<end-point>?action=post&module=release&resource=keybyemail&id=redj_ent&email=This email address is being protected from spambots. You need JavaScript enabled to view it.

Example (REST format)

<end-point>/post/release/keybyemail/redj_ent?email=This email address is being protected from spambots. You need JavaScript enabled to view it.

Response

{
    "status": "ok"
}

Notes

email is the user's account email on Joomla.

 

Generate key by authentication

Returns the license key for the specified package group.

Request parameters

action=post
module=release
resource=keybyauth
id=<package group>
username=<username>
password=<password>

Example

<end-point>?action=post&module=release&resource=keybyauth&id=redj_ent&username=user123&password=pass123

Example (REST format)

<end-point>/post/release/keybyauth/redj_ent?username=user123&password=pass123

Response

{
    "status": "ok",
    "email": "user email",
    "key": "license key"
}

Notes

username and password are the credentials used for the user's account on Joomla.

 

Validate key

Checks if a license key is valid for the specified package group.

Request parameters

action=post
module=release
resource=validate
id=<package group>
email=<user email>
key=<license key>

Example

<end-point>?action=post&module=release&resource=validate&id=redj_ent&email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Example (REST format)

<end-point>/post/release/validate/redj_ent?email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Response

{
    "status": "ok"
}

 

Verify key

Checks if a license key is valid for the specified package id.

Request parameters

action=post
module=release
resource=verify
id=<package id>
email=<user email>
key=<license key>

Example

<end-point>?action=post&module=release&resource=verify&id=redj_ent_190&email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Example (REST format)

<end-point>/post/release/verify/redj_ent_190?email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Response

{
    "status": "ok"
}

Notes

This method is intended to verify a license key over a specific package id before to download it.

 

Download package

Download the package for the specified package id.

Request parameters

action=post
module=release
resource=download
id=<package id>
email=<user email>
key=<license key>

Example

<end-point>?action=post&module=release&resource=download&id=redj_ent_190&email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Example (REST format)

<end-point>/post/release/verify/redj_ent_190?email=This email address is being protected from spambots. You need JavaScript enabled to view it.&key=fd8s809f89ds8f90sd81231sdsds323

Response

The binary package (as application/octet-stream)

 

Plugin Settings

jBackend Release System Plugin Settings

The following options are available for release system plugin:

Option Description
Folder Packages distribution folder path relative to Joomla root folder (JPATH_ROOT).
Package groups List of package groups. Packages in the same group share the same license key. Format is 'package group;groups[;hash;package name]' where package group is an unique identifier (e.g. redj_enterprise), groups is a list of user groups allowed to download packages in this group separated by commas (e.g. 1,3,5), hash is an optional random string used as seed for the generation of group's license keys, and package name is the human readable name of the package (e.g. ReDJ Enterprise).
Packages List of packages to distribute. Format is 'package id;package path[;package group]' where package id is an unique identifier (e.g. redj_ent_190), package path is the path of the package file relative to the packages distribution folder (e.g. private/joomla/redj/ReDJ1.9.0.zip), and package group is the group identifier (optional, not required for free downloads).

The Kunena Module is implemented with the plg_jbackend_kunena plugin. It provides functions related to Kunena forum for Joomla (topics and categories). Here is the list of supported methods.

Get the list of categories

Request parameters

action=get
module=kunena
resource=categories
parentid=<P> (optional) default to the root
levels=<L> (optional) 0=all levels, default is 1
unpublished=<0|1> (optional) 0=Hide (default), 1=Show

Example

<end-point>?action=get&module=kunena&resource=categories&parentid=<P>&levels=<L>

Example (REST format)

<end-point>/get/kunena/categories?parentid=<P>

Response

{
    "status": "ok",
    "categories": [
        {
            "id": "<category id>",
            "name": "<category name>",
            "alias": "<category alias>",
            "description": "<category description>",
            "parent_id": "<parent category id>",
            "level": "<category level>",
            "numTopics": "<number of category topics>",
            "numPosts": "<number of category posts>",
            "hits": "<number of hits>"
        }
    ]
}

 

Get a category

Request parameters

action=get
module=kunena
resource=categories
id=<N>

Example

<end-point>?action=get&module=kunena&resource=categories&id=<N>

Example (REST format)

<end-point>/get/kunena/categories/<N>

Response

{
    "status": "ok",
    "id": "<category id>",
    "name": "<category name>",
    "alias": "<category alias>",
    "description": "<category description>",
    "parent_id": "<category parent id>",
    "level": "<category language>",
    "numTopics": "<number of category topics>",
    "numPosts": "<number of category posts>",
    "hits": "<number of hits>",
    "icon": "<category icon>",
    "icon_id": "<category icon id>",
    "locked": "<locked status>",
    "pub_access": "<public access>",
    "pub_recurse": "<public recurse>",
    "review": "<review>",
    "allow_anonymous": "<allow anonymous>",
    "post_anonymous": "<post anonymous>",
    "allow_polls": "<allow polls>",
    "topic_ordering": "<topic ordering>",
    "last_topic_id": "<last topic id>",
    "last_post_id": "<last post id>",
    "last_post_time": "<last post time>"
}

 

Get the list of topics

Request parameters

action=get
module=kunena
resource=topics
catid=<C>
limit=<L> (optional)
offset=<O> (optional)
orderdir=<dir> (optional) asc, desc

Example

<end-point>?action=get&module=kunena&resource=topics&catid=<C>

Example (REST format)

<end-point>/get/kunena/topics?catid=<C>

Response

{
    "status": "ok",
    "total": "<total items>",
    "limit": <pagination limit>,
    "offset": <pagination offset>,
    "topics": [
        {
          "id": "<topic id>",
          "category_id": "<category id>",
          "subject": "<topic subject>",
          "locked": "<locked>",
          "hold": "<hold>",
          "posts": "<posts>",
          "hits": "<number of hits>",
          "attachments": "<attachments>",
          "first_post_id": "<first post id>",
          "first_post_time": "<first post time>",
          "first_post_userid": "<first post user id>",
          "first_post_message": "<first post message text>",
          "first_post_guest_name": "<first post guest name>",
          "last_post_id": "<last post id>",
          "last_post_time": "<last post time>",
          "last_post_userid": "<last post user id>",
          "last_post_message": "<last post message text>",
          "last_post_guest_name": "<last post guest name>"
        },
        ...
        {
        }
    ]
}

 

Get a topic

Request parameters

action=get
module=kunena
resource=topics
id=<N>

Example

<end-point>?action=get&module=kunena&resource=topics&id=<N>

Example (REST format)

<end-point>/get/kunena/topics/<N>

Response

{
  "status": "ok",
  "id": <topic id>,
  "category_id": "<category id>",
  "subject": "<subject>",
  "locked": "<locked>",
  "hold": "<hold>",
  "posts": "<posts>",
  "hits": "<number of hits>",
  "attachments": "<attachments>",
  "first_post_id": "<first post id>",
  "first_post_time": "<first post time>",
  "first_post_userid": "<first post user id>",
  "first_post_message": "<first post text message>",
  "first_post_guest_name": "<first post guest name>",
  "last_post_id": "<last post id>",
  "last_post_time": "<last post time>",
  "last_post_userid": "<last post user id>",
  "last_post_message": "<last post text message>",
  "last_post_guest_name": "<last post guest name>",
  "messages": [
    {
      "id": "<message id>",
      "parent": "<parent id>",
      "thread": "<thread id>",
      "catid": "<category id>",
      "name": "<user name>",
      "userid": "<user id>",
      "email": "<email>",
      "subject": "<message subject>",
      "time": "<message time>",
      "ip": "<ip address>",
      "topic_emoticon": "<topic emoticon>",
      "locked": "<locked>",
      "hold": "<hold>",
      "hits": "<number of hits>",
      "message": "<message>",
      "replynum": <number of replies>,
      "thankyou": [
        ...
      ]
    },
    ...
    {
        ...
    }
  ]
}
This module is only available with the Premium Subscription.

The Search Module is implemented with the plg_jbackend_search plugin. It provides functions related to Joomla search module. Here is the list of supported methods.

Search site

Request parameters

action=get
module=search
resource=site
searchword=<term>
searchphrase=<all> (optional)
limitstart=<offset> (optional)
limit=<limit> (optional)
ordering=<orderby> (optional)
areas[]=<area> (optional)

Example

<end-point>?action=get&module=search&resource=site?searchword=joomla&searchphrase=all&limitstart=10&limit=10&ordering=newest&areas[]=content

Example (REST format)

<end-point>/get/search/site?searchword=<term>

Response

{
    "status": "ok",
    "total": <T>,
    "limit": <L>,
    "offset": <O>,
    "pages_current": <C>,
    "pages_total": <P>,
    "results": [
        {
            "title": "<title>",
            "metadesc": "<metadesc>",
            "metakey": "<metakey>",
            "created": "<date created>",
            "language": "<language>",
            "catid": "<cid>",
            "text": "<text>",
            "section": "<section>",
            "slug": "<id:slug>",
            "catslug": "<id:slug>",
            "browsernav": "<browsernav>",
            "href": "<href>",
            "jcfields": "<jcfields>"
        },
        ...
    ]
}

Notes

searchphrase:
any, exact, all (default)

ordering:
newest (default), oldest, popular, alpha, category

areas:
an array of search areas (e.g. content)

Created date format is YYYY-MM-DD HH:MM:SS

Language can be "*" if any.

 

This module is only available with the Premium Subscription.
This module is intended for B2B integration. It exposes data that should not be made available on a public endpoint, so it must be used only on a private endpoint and somehow protected (e.g. through an API key).

The Community Builder Module is implemented with the plg_jbackend_comprofiler plugin. It provides functions related to Community Builder extension. Here is the list of supported methods.

List users

Request parameters

action=get
module=comprofiler
resource=users
limit=<L> (optional)
offset=<O> (optional)

Example

<end-point>?action=get&module=comprofiler&resource=users

Example (REST format)

<end-point>/get/comprofiler/users?limit=10&offset=2

Response

{
    "status": "ok",
    "total": <total>,
    "limit": <limit>,
    "offset": <offset>,
    "users": [
        {
            "id": "<userid>",
            ...
        },
        ...
        {
            "id": "<userid>",
            ...
        }
    ]
}

Notes

limit is the number of entries to return.

offset is the cursor starting point (0 based, start on record 16 means offset = 15).

If limit is not specified, offset is ignored.

Properties limit and offset in the response are present only when specified in the request.

 

Get user profile

Request parameters

action=get
module=comprofiler
resource=profile
id=<id>

Example

<end-point>?action=get&module=comprofiler&resource=profile&id=482

Example (REST format)

<end-point>/get/comprofiler/profile/482

Response

{
    "status": "ok",
    ...
}

 

Update user profile

Request parameters

action=put
module=comprofiler
resource=profile

 

JSON payload data

{
    "id": "<userid>",
    "name": "<name>",
    "username": "<username>",
    "email": "<email>",
    "password": "<password>",
    ...
}

Example

<end-point>?action=put&module=comprofiler&resource=profile

Example (REST format)

<end-point>/put/comprofiler/profile

Response

{
    "status": "ok"
}

Notes

The id parameter in the request payload is mandatory to identify the user profile to update.

Other mandatory fields are username, email, and name.

It is possible to specify any supported field in the payload.

 

The ZOO Module is implemented with the plg_jbackend_zoo plugin. It provides functions related to ZOO extension (applications, categories and items). Here is the list of supported methods.

Get the list of categories

Request parameters

action=get
module=zoo
resource=categories
app=<app id>

Example

<end-point>?action=get&module=zoo&resource=categories&app=<A>

Example (REST format)

<end-point>/get/zoo/categories?app=<A>

Response

{
    "status": "ok",
    "total": <T>,
    "categories": [
        {
            "id": "<category id>",
            "name": "<category name>",
            "alias": "<category alias>",
            "description": "<description>",
            "parent": "<parent id>"
        },
        ...
        {
            "id": "<category id>",
            "name": "<category name>",
            "alias": "<category alias>",
            "description": "<description>",
            "parent": "<parent id>"
        }
]}

 

Get a category

Request parameters

action=get
module=zoo
resource=categories
id=<N>
app=<app id>

Example

<end-point>?action=get&module=zoo&resource=categories&id=<N>&app=<A>

Example (REST format)

<end-point>/get/zoo/categories/<N>?app=<A>

Response

{
    "status": "ok",
    "id": "<category id>",
    "name": "<category name>",
    "alias": "<category alias>",
    "description": "<category description>",
    "application_id": "<application id>",
    "parent": "<parent id>",
    "ordering": "<ordering>",
    "content_subtitle": "<content subtitle>",
    "content_image": "<content image>",
    "content_image_width": "<content image width>",
    "content_image_height": "<content image height>",
    "metadata_title": "<meta title>",
    "metadata_description": "<meta description>",
    "metadata_keywords": "<meta keywords>",
    "metadata_robots": "<meta robots>",
    "metadata_author": "<meta author>"
}

 

Get the list of items

Request parameters

action=get
module=zoo
resource=items
category=<C>
limit=<L> (optional)
page=<P> (optional)
app=<app id>

Example

<end-point>?action=get&module=zoo&resource=items&category=<C>&app=<A>

Example (REST format)

<end-point>/get/zoo/items?category=<C>&app=<A>

Response

{
    "status": "ok",
    "total": <T>,
    "limit": <L>,
    "page": <P>,
    "items": [
        {
            "id": "<item id>",
            "name": "<item name>",
            "alias": "<item alias>",
            "created": "<created date>",
            "created_by": "<created by id>",
            "modified": "<modified date>",
            "modified_by": "<modified by id>",
            "publish_up": "<publish up date>",
            "publish_down": "<publish down date>"
        },
        ...
        {
            "id": "<item id>",
            "name": "<item name>",
            "alias": "<item alias>",
            "created": "<created date>",
            "created_by": "<created by id>",
            "modified": "<modified date>",
            "modified_by": "<modified by id>",
            "publish_up": "<publish up date>",
            "publish_down": "<publish down date>"
        }
]
}

Notes

Created and modified date format is YYYY-MM-DD HH:MM:SS

 

Get an item

Request parameters

action=get
module=zoo
resource=items
id=<N>
app=<app id>

Example

<end-point>?action=get&module=zoo&resource=items&id=<N>&app=<A>

Example (REST format)

<end-point>/get/zoo/items/<N>=?app=<A>

Response

{
    "status": "ok",
    "id": "<item id>",
    "name": "<item name>",
    "alias": "<item alias>",
    "application_id": "<application id>",
    "type": "<item type>",
    "created": "<created date>",
    "created_by": "<created by id>",
    "modified": "<modified date>",
    "modified_by": "<modified by id>",
    "publish_up": "<publish up date>",
    "publish_down": "<publish down date>",
    "priority": "<item priority>",
    "state": "<item state>",
    "searchable": "<is searchable>",
    "access": "<item access>",
    "hits": <item hits>,
    "metadata_title": "<meta title>",
    "metadata_description": "<meta description>",
    "metadata_keywords": "<meta keywords>",
    "metadata_robots": "<meta robots>",
    "metadata_author": "<meta author>",
    "enable_comments": "<enable comments>",
    "primary_category": "<primary category id>",
    "elements": {
        "<element 1 id>": {
            "identifier": "<element 1 id>",
            "type": "<element type>",
            "data": {
                "<field 1 name>": "<field 1 value>",
                ...
                "<field M name>": "<field M value>"
            }
        },
        ...
        "<element N id>": {
            "identifier": "<element N id>",
            "type": "<element type>",
            "data": {
                "<field 1 name>": "<field 1 value>",
                ...
                "<field L name>": "<field L value>"
            }
        },
    }
}

Notes

Created and modified date format is YYYY-MM-DD HH:MM:SS

When option Identify elements is set to No, the elements structure is different:

    "elements": [
        {
            "identifier": "<element 1 id>",
            "type": "image",
            "data": {
                "<field 1 name>": "<field 1 value>",
                ...
                "<field M name>": "<field M value>"
            }
        },
        {
            "identifier": "<element N id>",
            "type": "textarea",
            "data": {
                "<field 1 name>": "<field 1 value>",
                ...
                "<field L name>": "<field L value>"
            }
        }
    ]

 

Plugin Settings

jBackend ZOO Plugin Settings

The following options are available for user plugin:

Option Description
Update hits Update hits counter for each request.
Identify elements Use field identifier as key to build the elements in the response.
Include elements Include elements data in the list of items.
Name elements Use a slug name for elements (in lowercase without blanks).

To manage API Keys used to grant access to end-points go to menu Components > jBackend > Keys. A list of jBackend Keys will be shown:

jBackend Keys

Each key has the following properties:

Field: Description:
Key The enabling key
User The user associated to this key (to restrict access with key and to a single user)
Enabled endpoints If this key is enable on ALL endpoints or ONLY on selected endpoints
Selected endpoints The endpoints for which the key is enabled, when not enabled for ALL
Enabled on default If the key should also work on the default requests (i.e. /index.php?option=com_jbackend&view=request&...)
Daily requests Maximum number of daily requests allowed for the key (0 means unlimited)
Expiration date Key expiration date (0000-00-00 00:00:00 means never expires)
Comment Just a reminder for the key

For each key the following statistics fields are available:

Field: Description:
Hits Number of times the key was used
Last visit Last time the key was used
Current day Current day for daily requests limit
Current hits Hits of current day for daily requests limit

The API key, when required by the endpoint, must be included in any request using one of the following methods:

  • Adding api_key=<KEY> to the query params (for GET requests);
  • Adding api_key=<KEY> to the payload (for POST requests);
  • Adding api_key: <KEY> to the JSON payload (for JSON POST requests);
  • Adding Authorization: api_key <KEY> to the headers (in any case).

To access to end-points access logs go to menu Components > jBackend > Logs. A list of traced requests will be shown:

jBackend Logs

Each logged request has the following information:

Field:Description:
Endpoint The ID of the end-point that has received the request
Access type The type of access used on the end-point (free, user, API key)
Request time The date and time of the request
Duration Time required to serve the request (in seconds)
Error code The error code in case of request error
User ID The ID of the user when available
Key The API key used when available
Action The action of the request
Module The module of the request
Resource The resource of the request

It is possible to enable log trace for each end-point from the menu item options:

jBackend - Enable Trace

To access to configured apps go to menu Components > jBackend > Apps. A list of mobile apps will be shown:

jBackend Apps

Each registered app has the following information:

Field: Description:
Code The application unique code (it will be converted in lowercase)
Description An arbitrary description for the application
Project ID Google Project ID
Project number Google Project number (it will be used as Sender ID)
API key Google API key
SSL certificate Apple SSL certificate
Password Password for Apple SSL certificate

SSL Certificate

The SSL certificate for APNs must be in PEM format, and must include the certificate and the private key. If the private key is not protected by password, the password field must be empty.

Here is an example of the PEM certificate:

-----BEGIN CERTIFICATE-----
MIIFjDCCBHSgAwIBAgIIAYymZoETLVYwDQYJKoZIhvcNAQEFBQAwgZYxCzAJBgNV
BAYTAlVTMRMwEQYDVQQKDApBcHBsZSBJbmMuMSwwKgYDVQQLDCNBcHBsZSBXb3Js
ZHdpZGUgRGV2ZWxvcGVyIFJlbGF0aW9uczFEMEIGA1UEAww7QXBwbGUgV29ybGR3
aWRlIERldmVsb3BlciBSZWxhdGlvbnMgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkw
...
Nw2VqrNGWt42Jwt66015Ww+Toh5KaTisMJnR/UQsDOWErVUkmZBbrVkbIy/hhTYZ
b/MJRYBvnAQEtNU08eac3aqOEUFBt/Uu/HUigfvkxXOUdwMW4+wEB3uR2cLghrcA
XvVMho17NIY9rXy3bEIuzwDTUFoCOfBEBYqW00BJVTGkOa6EWDI7SZbuULtxlByD
4edJl4ukCdZrJaTfHWMPeGqnv+MIrxz6LNSeiulTyQw=
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,D20C57B1444E286C

uWXgF5I7fBBv2vY4N0yXiF9Uar+BRilhLUEuAcwDJJhWCFvnxVuBerck68Z5Zcbf
JNJlESBp7exD5sTgNfok12bRw9cXvhMibY70riCukfhJveSWXCYIgN9BYtUjZgdn
u8FZLtuRQH+HqY9OEjfQ9bcAiRX2a4uL1rKGCnyZShyWMRAtjLrOvT6Lzm8D59l6
7u8JcGlRAw+bdpDntwmB+17ep0zYd19uNRR5x9YKQfn9b55z1FiS+cBvwqqxnEtK
...
jNqc19lOabQjkmCPzJjUVeaR/7pco2pGhNoA9UpK9kgL82yuj4Vo/+VYbSw1a+/d
NkNKwOQTLttvKihEWDIZchoNP4vB/QnBo1DOAf+LRhtS3ja/FnLvsIouVeHo4OTL
NqJKpw2FLJUY2cxxfu0rVID6motRsSwR4vZ3RYoFf7lA9nQpWtaCDgxoohuFF4Jp
q+j5ZfY1MI0zQV56BnowR/0ocgzoibd6x3hTl076MGikjI6++Go6ng==
-----END RSA PRIVATE KEY-----

To access to the list of registered devices go to menu Components > jBackend > Devices. A list of mobile devices will be shown:

jBackend Devices

It is not possible to add or edit device manually. Device registration is performed through a request to the Push Module.

Each registered device has the following information:

Field:Description:
Token Device Token
App App code
Platform OS platform
IOS Alert App setting desired about alert on iOS (an optional registration param for the app)
IOS Badge App setting desired about badge on iOS (an optional registration param for the app)
IOS Sound App setting desired about sound on iOS (an optional registration param for the app)

In the current version alert, badge and sound fields are not used yet. They will be used in future, as example, to filter target devices for push notification sending.

For each device the following statistics fields are available:

Field:Description:
Hits Number of times the device has registered
Last visit Last time the device has registered
Push hits Number of push notifications sent to device
Last push Last time a push notification has been sent to device

To access to configured notifications go to menu Components > jBackend > Notifications. A list of notifications will be shown:

jBackend Notifications

Each notification has the following information:

Field: Description:
Title Notification title (used only on Android)
Message Notification message
Payload Payload of push notification for app (JSON format)
App App code
Platform OS platform
Target Target registered devices for the push notification (All, Selected users, Selected groups, Selected devices)
Target Users Users whose registered devices are target for the push notification
Target Groups Groups whose registered devices are target for the push notification
Target Devices Registerd devices target of the push notification
Context Application specific notification context. Not used yet (it will be used to filter recipients for push notifications)
Scheduled time Time scheduled to start sending out this notification on devices
Status Current sending status for this notification
Last run Last time this notification queue has been executed
Last device ID Device ID of the last notification sent in the last run

The Status of a notification can be:

Status: Description:
aborted (-2) The notification is "logically" deleted (in this state the notification is always skipped)
paused (-1) The notification is suspended (in this state the notification is always skipped)
scheduled (0) The notification is ready to be sent (sending will start at the scheduled time)
running (1) The notification is currently being processed
completed (2) The notification has been sent to all devices (job completed)

Using the buttons on the toolbar it is possible to change the status of selected notifications. It is also possible to "unlock" locked notifications. It could be useful, as example, when a notification is locked for too long, which could mean there was a problem on the scheduler and the resource was not released properly (see How notification sending works)

Since jBackend 3.3.0 each notification sent is logged into a database table. A management interface to access these logs will be provided in the next future.

How notification sending works

To start processing the pending notifications (with status scheduled and running) it is necessary to call a "trigger" function. The Push Module has a scheduler function that must be called on a regular basis (e.g. from a crontab) to trigger the sending of scheduled push notifications.

Scheduler logic

Each time the scheduler function is called, it select all pending notifications ordered by the scheduler time ascending (first the notification scheduled before). To be "pending" a notification must have a scheduled time less then current time, must be in status scheduled or running, and must be no locked (locked means the notification is currently in charge of another scheduler). If the pending list is not empty, the scheduler starts to process notifications once a time, until the total number of push notifications sent to devices reach the Batch size (max configured for the scheduler).

For the notification currently being processed, the scheduler first locks it, then start to send the notifications to all matching devices (sorted by device ID, so all devices will be checked only once, including new devices added while the notification is running) until the Batch size is reached or the devices are finished. In the first case the notification is unlocked and the scheduler ends. In the second case the notification state is set to completed, it is unlocked and the scheduler starts to process the next notification (if one) with the same rules.

With this processing logic it is possible to schedule and execute concurrent schedulers to increase volume of push notifications sent.

Push notification payload

It is possible to send a custom payload with each push notification. The payload must be a valid JSON, example:

{
  "alert": {
    "alertId": "1404999843555",
    "alertStatus": false
  }
}

Or:

{
  "id": "25"
}

How to get the JSON payload in the mobile app depends on the framework used. The following is an example using Ionic Framework with this Cordova Push notification plugin:

https://github.com/phonegap-build/PushPlugin

Android GCM

In the jBackend push plugin the payload hasthe following structure:

    $payload = array(
      'title'      => $notification['title'],
      'message'    => $notification['message'],
      'icon'       => 'icon',
      'data'       => $notification['payload']
    );

On the mobile app the push callback has the following code:

    window.onNotificationGCM = function(e) {
        switch (e.event) {
            case 'registered':
                if (e.regid.length > 0) {
                    $rootScope.$emit('push.registered', { 'token': e.regid });
                }
                break;
            case 'message':
                // Notification in foreground
                if (e.foreground) {
                    $log.debug('push notification in foreground');
                } else {
                    $log.debug('push notification in background');
                }
                $log.debug('push message payload ' + JSON.stringify(e.payload));
                $rootScope.$emit('push.received', { 'payload': e.payload.data });
                // e.payload.data is { "id": "25" }
                break;
            case 'error':
                $log.debug('push GCM error ' + e.msg);
                break;
            default:
                $log.debug('push GCM unknown event');
                break;
        }
    };

Apple APNs

In the jBackend push plugin the payload hasthe following structure:

    $body = array(
      'aps' => array(
          'alert' => array(
              'title' => $notification['title'],
              'body' => $notification['message']
          ),
          'sound' => 'default'
      ),
      'data' => $notification['payload']
    );

On the mobile app the push callback has the following code:

    window.onNotificationAPN = function(e) {
        if (e.alert) {
            $log.debug('push APN alert ' + e.alert);
        }
        if (e.sound) {
            $log.debug('push APN sound');
        }
        if (e.badge) {
            $log.debug('push APN badge ' + e.badge);
            pushNotification.setApplicationIconBadgeNumber(successBadgeHandler, errorBadgeHandler, e.badge);
        }
        $log.debug('push APN full event ' + JSON.stringify(e));
        $rootScope.$emit('push.received', JSON.parse(e.data));
        // e.data is { "id": "25" }
    };
Page 1 of 2