OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Support

Corona SDK

OneSignal Corona SDK Reference. Works with iOS, Android, and Windows Phone 8.

For Developers

Just starting with Corona?

Check out our Corona SDK Setup guide.

Initialization

Function

Initialize OneSignal

Function

iOS - Automatically Prompt Users to Enable Notifications

Function

Android, iOS - Automatically Display Notifications when app is in focus

Function

iOS - Open all URLs in In-App Safari Window

Registering Push

Function

Prompt Users to Enable Notifications

User IDs

Function

Get the User ID of the device

Tags

Function

View Tags from a User

Function

Add a Tag to a User

Function

Function

Delete a Tag from a User

Function

Data

Function

Prompt Users for Location

Function

Sync Anonymized User Email

Sending Notifications

Function

Send or schedule a notification to a user

Function

Delete a single app notification

Function

Delete all app notifications

Function

Opt users in or out of receiving notifications

Receiving Notifications

Function

When a notification is received by a device

Function

When a user takes an action on a notification

Function

Change how notifications are displayed to users

Function

Data that comes with a notification

Appearance

Function

Android - When user receives notification, vibrate device less

Function

Android - When user receives notification, do not play a sound

Debug

Function

Enable logging to help debug OneSignal implementation

Initialize

Init

Initializes OneSignal and lets you handle the opening of a push notification.

Parameter
Type
Description

appId

String

Your OneSignal app id, available in Keys & IDs

googleProjectNumber

String

Android - {googleProjectNumber: "############"} is required. This is a 10 to 14 digit number.

ios, windows phone 8 - Pass in ""

DidReceiveRemoteNotificationCallBack

Function

Gets called when the user opens the notification or one is received while the app is in use.

Callback

Parameter
Type
Description

message

String

The message text the user seen in the notification.

additionalData

Table

Key value pairs that were set on the notification.

stacked_notifications Table - Contains a Table for each notification that exists in the stack. message as well as keys listed above and ones you set with additional data will be available.

isActive

Boolean

true if your app was currently being used when a notification came in.

-- This function gets called when the user opens a notification or one is received when the app is open and active.
-- Change the code below to your app needs.
function DidReceiveRemoteNotification(message, additionalData, isActive)
    if (additionalData) then
        if (additionalData.discount) then
            native.showAlert( "Discount!", message, { "OK" } )
            -- Take user to your in-app store
        elseif (additionalData.actionSelected) then -- Interactive notification button pressed
            native.showAlert("Button Pressed!", "ButtonID:" .. additionalData.actionSelected, { "OK"} )
        end
    else
        native.showAlert("OneSignal Message", message, { "OK" } )
    end
end

local OneSignal = require("plugin.OneSignal")
OneSignal.Init("5eb5a37e-b458-11e3-ac11-000c2940e62c", "703122844262", DidReceiveRemoteNotification)

kOSSettingsKeyAutoPrompt

Function - iOS - formerly DisableAutoRegister

Automatically Prompt Users to Enable Notifications. Call DisableAutoRegister before Init to delay when the iOS system prompt asks for permissions to show push notifications. You can then call RegisterForNotifications after the player is done with your tutorial for example. This improves the opt-in rate for your app. This only affects iOS as Android devices always automatically register silently.

Testing
If you already answered the iOS Notification Permissions prompt you can reset it by following instructions here.

Gotchas
If your using this function, IdsAvailableCallback, and applicationIconBadgeNumber or any local notifications before calling RegisterForNotifications then the iOS system prompt asking for push permissions will show sooner and IdsAvailableCallback may not fire.

OneSignal.DisableAutoRegister()

kOSSettingsKeyInFocusDisplayOption

Interface Element - iOS 10+

Setting to control how OneSignal notifications will be shown when one is received while your app is in focus, for apps targeting iOS 10+.

Notification - native notification display while user has app in focus (can be distracting).
InAppAlert (Default) - native alert dialog display, which can be helpful during development.
None - notification is silent.

Disable Before Launch

We recommend you set this to None prior to launching your app, so users do not get interrupted while using your app.

iOS 9 AND BELOW - the Notification setting will fall back to InAppAlert .

kOSSettingsKeyInAppLaunchURL

Function - iOS - Coming Soon

true (Default) - Open all URLs in in-app Safari window
false - disables the display of launch URLs in-app but instead open the URL in Safari or other app (if deep linked or custom URL scheme passed).

Registering Push

RegisterForNotifications

Function - ios

Use this only if you called DisableAutoRegister before Init. This will show the iOS system prompt to ask for push permissions. If the user presses yes they will be subscribed for push notifications on OneSignal.com.

OneSignal.RegisterForNotifications()

User IDs

IdsAvailableCallback

Function

Lets you retrieve the OneSignal player id and device token. Your callback function is called after the device is successfully registered with OneSignal. If the device could not be successfully registered with Apple/Google or DisableAutoRegister was called then the pushToken parameter with be nil. If later the device registers with Apple/Google then the callback will be fired a 2nd time with both ids filled. Once the callback fires with both ids it will not be called again unless you call IdsAvailableCallback again.

Parameter
Type
Description

idsAvailableCallback

Function

Function that will get called when the user id is retrieved from OneSignal.

function IdsAvailable(userID, pushToken)
    print("PLAYER_ID:" .. userID)
    if (pushToken) then -- nil if user did not accept push notifications on iOS
        print("PUSH_TOKEN:" .. pushToken)
    end
end

OneSignal.IdsAvailableCallback(IdsAvailable)

Tags

GetTags

Function

Retrieve a table of tags that have been set on the player from the OneSignal server.

Parameter
Type
Description

tagsAvailableCallback

Function

Function that gets called when the tags are retrieved from the OneSignal server.

Returns
Type
Description

keyValuePairs

Table

Table of key value pairs retrieved from the OneSignal server.

function printAllTags(tags)
   for key,value in pairs(tags) do
      print( key, value )
   end
end

OneSignal.GetTags(printAllTags)

SendTag

Function

Tag a user with custom data so you can create segments on onesignal.com to target these users. Recommend using SendTags over SendTag if you need to set more than one tag on a user at a time.

Parameters
Type
Description

key

String

Key of your choosing to create or update.

value

String

Value to set on the key. NOTE: Passing in a blank String deletes the key, you can also call DeleteTag or DeleteTags. (TODO CONFIRM THIS ELABORATION)

OneSignal.SendTag("CoronaTag1", "value1")

SendTags

Function

Set multiple tags on a player with one call.

Parameter
Type
Description

keyValuePairs

Table

Key value pairs of your choosing to create or update.

OneSignal.SendTags({["CoronaTag2"] = "value2",["CoronaTag3"] = "value3"})

DeleteTag

Function

Delete a tag by its key from the user that was set with SendTag or SendTags calls. Recommend using DeleteTags over DeleteTag if you need to delete more than one tag on a user at a time.

Parameter
Type
Description

key

String

Key to remove from the tags set on a user.

OneSignal.DeleteTag("CoronaTag1")

DeleteTags

Function

Delete tags by their keys from the user that were set with SendTag or SendTags calls.

Parameter
Type
Description

key

Table

List of keys to delete off the user.

OneSignal.DeleteTags({"key1", "key2"})

Data

PromptLocation

Function - ios

Prompts the user for location permission to allow geotagging based on the "Location radius" filter in Segments.

OneSignal.PromptLocation();

Required build.settings:

settings =
{
    iphone =
    {
        plist =
        {
            NSLocationUsageDescription = "Location permission prompt text",
            NSLocationWhenInUseUsageDescription = "Location permission prompt text",
        },
    },
}

SyncHashedEmail

Function - Coming Soon

Sends the user's email as an anonymized hash to prevent duplicated users.

Sending Notifications

PostNotification

Function

Allows you to send notifications from user to user or schedule ones in the future to be delivered to the current device.

Parameter
Type
Description

parameters

Table

Contains notification options, see Create Notification POST call for all options.

onSuccess

function

(Optional) callback fires when the notification was created on OneSignal's server.

returnedJson table (JSON) - response from OneSignal's server.

onFailure

function

callback fires when the notification failed to create

returnedJson table (JSON) - response from OneSignal's server.

-- Creates a notification to be deliver to this device as a test.
function IdsAvailable(userID, pushToken)
    if (pushToken) then
        local notification = {
            ["contents"] = {["en"] = "test"}
        }
        notification["include_player_ids"] = {userID}
        
        OneSignal.PostNotification(notification,
            function(jsonData)
                native.showAlert( "DEBUG", "POST OK!!!", { "OK" } )
                local json = require "json"
                print(json.encode(jsonData))
            end,
            function(jsonData)
                native.showAlert( "DEBUG", "POST NOT OK!!!", { "OK" } )
                local json = require "json"
                print(json.encode(jsonData))
            end
        )
    end
end

OneSignal.IdsAvailableCallback(IdsAvailable)

cancelNotification

Function - Android - Coming Soon

Delete a single app notification

ClearAllNotifications

Function

Use this to clear all push notifications from your app from the device. Use this function instead of system.cancelNotification() as it does not clear Android remote notifications from OneSignal.

OneSignal.ClearAllNotifications()

SetSubscription

Function

You can call this function with false to opt users out of receiving all notifications through OneSignal. You can pass true later to opt users back into notifications.

Parameter
Type

enable

boolean

OneSignal.SetSubscription(false)

Receiving Notifications

OSHandleNotificationReceivedBlock

Function - Coming Soon

OSNotificationOpenedResult

Function - Coming Soon

OSNotification

Function - Coming Soon

OSNotificationAction

Function - Coming Soon

OSNotificationDisplayType

Function - Coming Soon

OSNotificationPayload

Function - Coming Soon

Appearance

enableVibrate

Function - Android

By default OneSignal always vibrates the device when a notification is displayed unless the device is in a total silent mode. Passing false means that the device will only vibrate lightly when the device is in it's vibrate only mode. If both EnableVibrate and EnableSound are set to false then the device will never vibrate or make a sound.

You can link this action to a UI button to give your user a vibration option for your notifications.

Parameter
Type
Description

enable

boolean

false to disable vibrate, true to re-enable it.

OneSignal.EnableVibrate(false)

enableSound

Function - Android

By default OneSignal plays the system's default notification sound when the device's notification system volume is turned on. Passing false means that the device will only vibrate unless the device is set to a total silent mode. If both EnableVibrate and EnableSound are set to false then the device will never vibrate or make a sound.

You can link this action to a UI button to give your user a different sound option for your notifications.

Parameter
Type
Description

enable

boolean

false to disable sound, true to re-enable it.

OneSignal.EnableSound(false)

Debug

SetLogLevel

Function

Enable logging to help debug if you run into an issue setting up OneSignal. The logging levels are available with increasingly more information, as follows:
0 = None
1 = Fatal
2 = Errors
3 = Warnings
4 = Info
5 = Debug
6 = Verbose

Parameters
Type
Description

logLevel

Integer

Sets the logging level to print the iOS Xcode log or the Android LogCat log.

visualLevel

Integer

Sets the logging level to show as alert dialogs.

-- Will show popup dialogs when the devices registers with Apple/Google and with OneSignal.
-- Errors will be shown as popups too if there are any issues.
OneSignal.SetLogLevel(4, 4)

Corona SDK

OneSignal Corona SDK Reference. Works with iOS, Android, and Windows Phone 8.

For Developers