- Select ref document -

Push notifications API documentation

version 1.2.144

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.

Functions

push.cancel

push.cancel(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

id

number the numeric id of the local push notification

id

number the numeric id of the local push notification

push.get_all_scheduled

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).

Returns

data

table table with all data associated with all scheduled notifications

data

table table with all data associated with all scheduled notifications

push.get_scheduled

push.get_scheduled(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

id

number the numeric id of the local push notification

id

number the numeric id of the local push notification

Returns

data

table table with all data associated with the notification

data

table table with all data associated with the notification

push.register

push.register(notifications, callback)

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

Parameters

notifications

table the types of notifications to listen to.

callback

function(self, token, error) register callback function.

self

object The current object.

token

string The returned push token if registration is successful.

error

table A table containing eventual error information.

notifications

table the types of notifications to listen to.

callback

function(self, token, error) register callback function.

self

object The current object.

token

string The returned push token if registration is successful.

error

table A table containing eventual error information.

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.schedule

push.schedule(time, title, alert, payload, 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

time

number number of seconds into the future until the notification should be triggered

title

string localized title to be displayed to the user if the application is not running

alert

string localized body message of the notification to be displayed to the user if the application is not running

payload

string JSON string to be passed to the registered listener function

notification_settings

table table with notification and platform specific fields

action
string The alert action string to be used as the title of the right button of the alert or the value of the unlock slider, where the value replaces "unlock" in "slide to unlock" text.
badge_count
number The numeric value of the icon badge.
badge_number
Deprecated! Use badge_count instead
priority
number The priority is a hint to the device UI about how the notification should be displayed. There are five priority levels, from -2 to 2 where -1 is the lowest priority and 2 the highest. Unless specified, a default priority level of 2 is used.
time

number number of seconds into the future until the notification should be triggered

title

string localized title to be displayed to the user if the application is not running

alert

string localized body message of the notification to be displayed to the user if the application is not running

payload

string JSON string to be passed to the registered listener function

notification_settings

table table with notification and platform specific fields

action
string The alert action string to be used as the title of the right button of the alert or the value of the unlock slider, where the value replaces "unlock" in "slide to unlock" text.
badge_count
number The numeric value of the icon badge.
badge_number
Deprecated! Use badge_count instead
priority
number The priority is a hint to the device UI about how the notification should be displayed. There are five priority levels, from -2 to 2 where -1 is the lowest priority and 2 the highest. Unless specified, a default priority level of 2 is used.

Returns

id

number unique id that can be used to cancel or inspect the notification

err

string error string if something went wrong, otherwise nil

id

number unique id that can be used to cancel or inspect the notification

err

string error string if something went wrong, otherwise nil

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.set_badge_count

push.set_badge_count(count)

Set the badge count for application icon. This function is only available on iOS.

Parameters

count

number badge count

count

number badge count

push.set_listener

push.set_listener(listener)

Sets a listener function to listen to push notifications.

Parameters

listener

function(self, payload, origin, activated) listener callback function. Pass an empty function if you no longer wish to receive callbacks.

self
object The current object
payload
function the push payload
origin
constant push.ORIGIN_LOCAL or push.ORIGIN_REMOTE
activated
boolean true or false depending on if the application was activated via the notification.
listener

function(self, payload, origin, activated) listener callback function. Pass an empty function if you no longer wish to receive callbacks.

self
object The current object
payload
function the push payload
origin
constant push.ORIGIN_LOCAL or push.ORIGIN_REMOTE
activated
boolean true or false depending on if the application was activated via the notification.

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

Constants

push.NOTIFICATION_ALERT

push.NOTIFICATION_BADGE

push.NOTIFICATION_SOUND

push.ORIGIN_LOCAL

push.ORIGIN_REMOTE

push.PRIORITY_DEFAULT

The default notification priority. Only available on Android.

push.PRIORITY_HIGH

Priority for more important notifications or alerts. Only available on Android.

push.PRIORITY_LOW

Priority for items that are less important. Only available on Android.

push.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.

push.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.