API reference (extension-push)

C++

Lua

Extension

Version

Extension-push

Functions and constants for interacting with local, as well as Apple''s and Google''s push notification services. These API's only exist on mobile platforms. [icon:ios] [icon:android]


Namespace:	`push`
Include:	`#include <>`

CONSTANTS
NOTIFICATION_BADGE
NOTIFICATION_SOUND
NOTIFICATION_ALERT
ORIGIN_LOCAL
ORIGIN_REMOTE
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

FUNCTIONS
void push.register(table notifications, function callback)
void push.set_listener(function listener)
void push.set_badge_count(number count)
void push.schedule(number time, string title, string alert, string payload, table notification_settings)
void push.cancel(number id)
void push.cancel_all_issued()
void push.get_scheduled(number id)
void push.get_all_scheduled()

Functions

push.register

void push.register(table notifications, function callback)

Send a request for push notifications. Note that the notifications table parameter is iOS only and will be ignored on Android.

PARAMETERS

`table`	`notifications`	The types of notifications to listen to. [icon:ios]
`function`	`callback`	Register callback function.

EXAMPLES

local function push_listener(self, payload, origin)
     -- The payload arrives here.
end

function init(self)
     local alerts = {push.NOTIFICATION_BADGE, push.NOTIFICATION_SOUND, push.NOTIFICATION_ALERT}
     push.register(alerts, function (self, token, error)
     if token then
          -- NOTE: %02x to pad byte with leading zero
          local token_string = ""
          for i = 1,#token do
              token_string = token_string .. string.format("%02x", string.byte(token, i))
          end
          print(token_string)
          push.set_listener(push_listener)
     else
          -- Push registration failed.
          print(error.error)
     end
end

local function push_listener(self, payload, origin)
     -- The payload arrives here.
end

function init(self)
     push.register({}, function (self, token, error)
         if token then
              print(token)
              push.set_listener(push_listener)
         else
              -- Push registration failed.
              print(error.error)
         end
    end)
end

push.set_listener

void push.set_listener(function listener)

Sets a listener function to listen to push notifications.

PARAMETERS

function listener Listener callback function.

EXAMPLES

Set the push notification listener.

local function push_listener(self, payload, origin, activated)
     -- The payload arrives here.
     pprint(payload)
     if origin == push.ORIGIN_LOCAL then
         -- This was a local push
         ...
     end

     if origin == push.ORIGIN_REMOTE then
         -- This was a remote push
         ...
     end
end

local init(self)
     ...
     -- Assuming that push.register() has been successfully called earlier
     push.set_listener(push_listener)
end

push.set_badge_count

void push.set_badge_count(number count)

Set the badge count for application icon. This function is only available on iOS. [icon:ios]

PARAMETERS

number count Badge count

push.schedule

void push.schedule(number time, string title, string alert, string payload, table notification_settings)

Local push notifications are scheduled with this function. The returned `id` value is uniquely identifying the scheduled notification and can be stored for later reference.

PARAMETERS

`number`	`time`	Number of seconds into the future until the notification should be triggered.
`string`	`title`	Localized title to be displayed to the user if the application is not running.
`string`	`alert`	Localized body message of the notification to be displayed to the user if the application is not running.
`string`	`payload`	JSON string to be passed to the registered listener function.
`table`	`notification_settings`	Table with notification and platform specific fields

RETURNS

EXAMPLES

This example demonstrates how to schedule a local notification:

-- Schedule a local push in 3 seconds
local payload = '{ "data" : { "field" : "Some value", "field2" : "Other value" } }'
id, err = push.schedule(3, "Update!", "There are new stuff in the app", payload, { action = "check it out" })
if err then
     -- Something went wrong
     ...
end

push.cancel

void push.cancel(number id)

Use this function to cancel a previously scheduled local push notification. The notification is identified by a numeric id as returned by `push.schedule()`.

PARAMETERS

number id The numeric id of the local push notification

push.cancel_all_issued

void push.cancel_all_issued()

Use this function to cancel a previously issued local push notifications.

PARAMETERS

push.get_scheduled

void push.get_scheduled(number id)

Returns a table with all data associated with a specified local push notification. The notification is identified by a numeric id as returned by `push.schedule()`.

PARAMETERS

number id The numeric id of the local push notification.

RETURNS

Returns a table with all data associated with all scheduled local push notifications. The table contains key, value pairs where the key is the push notification id and the value is a table with the notification data, corresponding to the data given by `push.get_scheduled(id)`.

PARAMETERS

RETURNS

Extension-push

Functions

Constants