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    Discussions

Corona SDK

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

📘

Just starting with Corona?

Check out our Corona SDK Setup guide.

ParameterData TypeDescription
Debugging
setLogLevelMethodEnable logging to help debug OneSignal implementation
Initialization
InitFunctionInitialize OneSignal
kOSSettingsKeyAutoPromptFunctioniOS - Automatically prompt users to enable notifications
kOSSettingsKeyInFocusDisplayOptionFunctionAndroid, iOS - Automatically display notifications when app is in focus
kOSSettingsKeyInAppLaunchURLFunctioniOS - Open all URLs in In-App Safari window
Registering Push
RegisterForNotificationsFunctionPrompt users to enable notifications
User IDs
IdsAvailableCallbackFunctionGet the user ID of the device
Tags
GetTagsFunctionView tags from a user
SendTagFunctionAdd a tag to a user
SendTagsFunction
DeleteTagFunctionDelete a tag from a user
DeleteTagsFunction
Data
PromptLocationFunctionPrompt users for location
Sending Notifications
PostNotificationFunctionSend or schedule a notification to a user
cancelNotificationFunctionDelete a single app notification
ClearAllNotificationsFunctionDelete all app notifications
SetSubscriptionFunctionOpt users in or out of receiving notifications
Receiving Notifications
OSHandleNotificationReceivedBlockFunction
OSNotificationOpenedResultFunction
OSNotificationFunctionWhen a notification is received by a device
OSNotificationActionFunctionWhen a user takes an action on a notification
OSNotificationDisplayTypeFunctionChange how notifications are displayed to users
OSNotificationPayloadFunctionData that comes with a notification
Appearance
enableVibrateFunctionAndroid - When user receives notification, vibrate device less
enableSoundFunctionAndroid - When user receives notification, do not play a sound

Initialize

Init

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

ParameterTypeDescription
appIdStringYour OneSignal app id, available in Keys & IDs
googleProjectNumberString

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



ios, windows phone 8 - Pass in ""

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

Callback

ParameterTypeDescription
messageStringThe message text the user seen in the notification.
additionalDataTableKey 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.
isActiveBooleantrue 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.

ParameterTypeDescription
idsAvailableCallbackFunctionFunction 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.

ParameterTypeDescription
tagsAvailableCallbackFunctionFunction that gets called when the tags are retrieved from the OneSignal server.
ReturnsTypeDescription
keyValuePairsTableTable 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.

ParametersTypeDescription
keyStringKey of your choosing to create or update.
valueStringValue 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.

ParameterTypeDescription
keyValuePairsTableKey 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.

ParameterTypeDescription
keyStringKey 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.

ParameterTypeDescription
keyTableList 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",
        },
    },
}

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.

ParameterTypeDescription
parametersTableContains notification options, see Create Notification POST call for all options.
onSuccessfunction(Optional) callback fires when the notification was created on OneSignal's server.

returnedJson table (JSON) - response from OneSignal's server.
onFailurefunctioncallback 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.

ParameterType
enableboolean
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.

ParameterTypeDescription
enablebooleanfalse 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.

ParameterTypeDescription
enablebooleanfalse to disable sound, true to re-enable it.
OneSignal.EnableSound(false)

Updated 3 months ago


Corona SDK


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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.