Solar2D SDK

📘

Just starting with Solar2D?

Check out our Solar2D SDK Setup guide.

Initialize

Init

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

Callback

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

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

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

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

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

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.

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

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

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

OneSignal.GetTags(printAllTags)

SendTag

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.

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

SendTags

Set multiple tags on a player with one call.

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

DeleteTag

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.

OneSignal.DeleteTag("CoronaTag1")

DeleteTags

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

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

Data

PromptLocation

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

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

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

Delete a single app notification

ClearAllNotifications

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

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.

OneSignal.SetSubscription(false)

Receiving Notifications

OSHandleNotificationReceivedBlock

OSNotificationOpenedResult

OSNotification

OSNotificationAction

OSNotificationDisplayType

OSNotificationPayload

Appearance

enableVibrate

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.

OneSignal.EnableVibrate(false)

enableSound

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.

OneSignal.EnableSound(false)