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

Register for push notifications on iOS. Note that the token needs to be converted on this platform.

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

Register for push notifications on Android.

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


push.get_all_scheduled

void push.get_all_scheduled()

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


Constants

NOTIFICATION_BADGE

Badge notification type.


NOTIFICATION_SOUND

Sound notification type.


NOTIFICATION_ALERT

Alert notification type.


ORIGIN_LOCAL

Local push origin.


ORIGIN_REMOTE

Remote push origin.


PRIORITY_MIN

This priority is for items might not be shown to the user except under special circumstances, such as detailed notification logs. Only available on Android. [icon:android]


PRIORITY_LOW

Priority for items that are less important. Only available on Android. [icon:android]


PRIORITY_DEFAULT

The default notification priority. Only available on Android. [icon:android]


PRIORITY_HIGH

Priority for more important notifications or alerts. Only available on Android. [icon:android]


PRIORITY_MAX

Set this priority for your application's most important items that require the user's prompt attention or input. Only available on Android. [icon:android]