Mobile OneSignal

The Mobile OneSignal plugin is specifically designed to implement native mobile push notifications, post notifications and in-app messages features through the OneSignal Android SDK and OneSignal iOS SDK in both Android and iOS, for games built using Construct 3.


The OneSignal service has lots of features and tools, and the Mobile OneSignal plugin has integrated all of the features in both the OneSignal Android SDK and OneSignal iOS SDK.


The OneSignal service is a free service, although you can still opt for paid plans with additional benefits.

PlayFab API v2.png

Introduction

Step 1.png

The Construct Master Collection supports the full and easy integration of native mobile Android SDKs and iOS SDKs for both Construct 3 and Construct 2.


Please click here to learn more about Mobile.

Features


The Mobile OneSignal plugin is specifically designed to implement native mobile push notifications, post notifications and in-app messages features through the OneSignal Android SDK and OneSignal iOS SDK in both Android and iOS, for games built using Construct 3.


The OneSignal service has lots of features and tools, and the Mobile OneSignal plugin has integrated all of the features in both the OneSignal Android SDK and OneSignal iOS SDK.


The OneSignal service is a free service, although you can still opt for paid plans with additional benefits.


Here are some of the native features of the mobile plugin:

  • OneSignal service integration

  • OneSignal Android SDK

  • OneSignal iOS SDK

  • Full OneSignal API integration

  • Push notifications

  • Post notifications

  • In-app messages

  • GDPR

  • Consent dialog

  • iOS permission prompt

  • Tags

  • Triggers

  • External User Id

  • Appreances

  • Styles

  • Vibration features

  • Sound features

  • Email features

  • Location features

  • OneSignal is a free service, although you can still opt for paid plans with additional benefits.

  • Well maintained and fully tested for production release.


For more information about native mobile or Android and iOS features, please click here to learn the introductory lessons to Mobile.


Platform Integration


Here are some of the platforms that are natively supported:

  • Android

  • iOS

  • Native Android

  • Native iOS


Build Support


Here are some of the supported build options:


Editor Features


Here are some of the features in the Construct editor:

  • Construct 3

 
 

How to use?

It is easy to use the Mobile OneSignal plugin, you will only need to follow the steps below.

1. The first step is to add the Mobile OneSignal object into the project.


2. The next step is to create your own OneSignal account.


3. After creating your OneSignal account, create an application and then you will be required some credentials.



4. From your Construct 3 project, select the Mobile OneSignal object and then look over the Properties Bar.


5. Input your OneSignal App ID into the App ID field in the configuration section. Click to visit the instructions guide page.


6. By default, the rest of the property configurations in the Mobile OneSignal plugin upon adding should be ready for release and production. Unless you know what you are doing, please do not change any settings aside from the App ID field.


7. Build your application through any of the build options, then start sending native mobile push notifications, and other OneSignal SDK features.

 
 

Documentation

The Mobile OneSignal plugin is specifically designed to implement native mobile push notifications, post notifications and in-app messages features through the OneSignal Android SDK and OneSignal iOS SDK in both Android and iOS, for games built using Construct 3.


 

Actions, Conditions & Expressions

Actions

press to zoom

press to zoom

press to zoom

press to zoom
1/4

The following action groups:

  • Privacy

  • iOS

  • Tags

  • Tags - Batched

  • Data

  • Sending notifications

  • In-app messaging - Trigger

  • In-app messaging - Trigger - Batched

  • In-app messaging - Click

  • Email

  • External Ids

  • Notification

  • User properties

  • Deprecated

Privacy

  • Provide user consent - If your application is set to require the user's privacy consent, you can provide this interface for the user to give consent. Until enabled, the OneSignal SDK will not fully initialize.

  • Consent - Check to acknowledge that the user has provided consent.


  • Update if user provided consent - Checks if the user has already provided privacy consent. Callback trigger "On update if user provided consent" fires and toggles the condition "Is consent provided".




iOS

  • Prompt for push notifications permission - Prompt the user for notifications permission. This will launch the iOS notification permission consent dialog. You can only prompt once, so make sure to specify the benefits.




Tags

  • Get tags - Retrieve a list of tags that have been set on the user from the OneSignal servers.


  • Send tag - Tag a user based on an app event of your choosing so you can later create segments through OneSignal's "Segments" feature to target users.

  • Key - Key of your choosing to create or update.

  • Value - Value to set for the key. [Note] Passing in a blank string deletes the key, you can also call the "Delete tag" or "Delete tags" action.


  • Delete tag - Deletes a single tag that was previously set on a user with "Send tag" or "Send tags" action.

  • Key - Key to remove.




Tags - Batched

  • Send tags - Tag a user based on an app event of your choosing so you can later create segments through OneSignal's "Segments" feature to target users. List is collected from previously set plans.


  • Delete tags - Deletes one or more tags that were previously set on a user through the "Send Tag" or "Send Tags" action. List collected from previously set plans.


  • Plan send tag - Plan a tag to add in the next "Send tags" action.

  • Key - Key of your choosing to create or update.

  • Value - Value to set for the key. [Note] Passing in a blank string deletes the key, you can also call the "Delete tag" or "Delete tags" action.


  • Plan delete tag - Plan to add a tag for removal in the next "Delete tags" action.

  • Key - Key to remove.




Data

  • Prompt location dialog - Prompts the user for location permissions consent. If user gives consent in the dialog prompt, geotagging will be allowed so that you can send notifications to users based on their location.




Sending notifications


  • Clear notifications - Clears all notifications in the "Notification Center", also known as the mobile notification shade.




In-app messaging - Trigger

  • Add trigger - Add a trigger, may show an in-app message if its triggers' conditions are met.

  • Key - Key for the trigger.

  • Value - Value for the trigger.


  • Remove trigger - Removes a single trigger with the given key, may show an in-app message if its triggers' conditions are met.

  • Key - Key for trigger to remove.


  • Get trigger value - Gets the trigger value from a provided trigger key.

  • Key - Key for the trigger.




In-app messaging - Trigger - Batched

  • Add triggers - Add a key-value object of triggers, may show an in-app message if its triggers' conditions are met. List collected from previously set plans.


  • Remove triggers - Removes a list of triggers based on a collection of keys, may show an in-app message if its triggers' conditions are met. List collected from previously set plans.


  • Plan add trigger - Plan a trigger to add in the next "Add triggers" action.

  • Key - Key for the trigger.

  • Value - Value for the trigger.


  • Plan remove trigger - Plan to add a trigger for removal in the next "Remove triggers" action.

  • Key - Key for trigger to remove.




In-app messaging - Click

  • Pause in-app messages - Allows you to temporarily pause all in-app messages. You may want to do this while the user is watching a video playing a match in your game to make sure they don't get interrupted at a bad time.

  • Toggle - Check to pause, and uncheck to resume.




Email

  • Set email - This allows you to set the user's email address for the OneSignal service.

  • Email address - The email address of the user. Make sure it is verified and unique.

  • Email auth-token - Authentication token from your backend server.


  • Log out email - If your app implements logout functionality, you can call this to dissociate the email from the device.




External Ids

  • Set external user id - If your system assigns unique identifiers to users, it can be annoying to have to also remember their OneSignal user id as well. To make things easier, OneSignal now allows you to set an [external_id] for your users. Simply call this action, pass in your custom user id as a string. And then, from now on when you send push notifications, you can use 'include_external_user_ids' instead of 'include_player_ids'.

  • User id - User identification provided by your backend server. For example, the user's PlayFab Id.


  • Remove external user id - User id provided by your backend server. For example, the user's PlayFab Id.




Notification

  • Set push disabled - Enable or disable receiving of push notifications. If checked, this unsubscribes the user from the OneSignal service in receiving push notifications.

  • Toggle - Check to stop receiving push notifications, and uncheck to start/resume receiving of push notifications.



User properties

  • Get device state - Get the current device's notification subscription and permission state.



Deprecated

  • Enable vibrate - [Deprecated] By default OneSignal always vibrates the device when a notification is displayed unless the device is in a total silent mode. Setting unchecked means that the device will only vibrate lightly when the device is in its vibrate only mode.

  • Toggle - Set unchecked to disable vibrate, set checked to enable/re-enable vibrate.


  • Enable sound - [Deprecated] By default OneSignal plays the system's default notification sound when the device's notification system volume is turned on. You may also set "custom sounds" for notifications. Setting unchecked means that the device will only vibrate unless the device is set to a total silent mode.

  • Toggle - Set unchecked to disable sound, set checked to enable/re-enable sound.


  • Set subscription - [Deprecated] You can call this method and set unchecked to opt users out of receiving push notifications from OneSignal. You can set checked later to opt users back into receiving notifications. This unsubscribes the user from OneSignal, but the device will still show as subscribed to push.

  • Toggle - Check to receive push notifications, uncheck to disable receiving push notifications.


  • Get permission subscription state - [Deprecated] Get the current notifications and permissions state.

Conditions

The following condition groups:

  • Privacy

  • iOS

  • Status

  • Tags

  • Sending notifications

  • In-app messaging - Trigger

  • Email

  • Notification

  • Email - Status

  • Subscription status

  • User properties

  • Deprecated

press to zoom

press to zoom

press to zoom

press to zoom
1/4

Privacy

  • Is consent provided - Checks if the user has given privacy consent.


  • On update if user provided consent - Callback trigger fires after running the action "Update if user provided consent".


  • Is requiring consent - Checks if the application requires user consent for privacy compliance, configured in the plugin properties.



iOS

  • On prompt push notification permission - Trigger fires as soon as the user accepts or declines notifications from the iOS notification permission prompt.

  • Response - The user's response from the permission prompt.



Status

  • On subscription status changed - Callback trigger fires when the subscription status changes.


  • On permission status changed - Callback trigger fires when the permission status changes.



Tags

  • On get tags - Callback trigger after the "Get tags" action has finished fetching.



Sending notifications

On post notification - Callback trigger fires when the notification was posted to OneSignal's servers.

  • On post notification failure - Callback trigger fires when post notification fails.



In-app messaging - Trigger

  • On get trigger value - Callback trigger fires when the "Get trigger value" action has finished fetching.

  • Key - The trigger key.



In-app messaging - Click

  • On in-app message clicked - Trigger fires when an in-app message notification is tapped on.



Email

  • On set email - Callback trigger fires when the "Set email" action succeeds.


  • On set email failure - Callback trigger fires when the "Set email" action fails.


  • On logout email - Callback trigger fires when the "Logout email" action succeeds.


  • On logout email failure - Callback trigger fires when the "Logout email" action fails.



Notification

  • On notification received - Triggers fires when the app is running in the foreground at the time the notification is received.


  • On notification opened - Trigger fires when a notification is tapped on from the notification shade (ANDROID) or notification center (iOS), or when closing an alert notification shown in the app.



Email - Status

  • On email status changed - Callback trigger fires when the email subscription observer to track changes to email subscriptions (ie. the user sets their email or logs out) detects a change.



Subscription status

  • Is receiving notifications - Checks if the device is subscribed to receive push notifications.



User properties

  • On get device state - Callback trigger fires after the "Get device state" action has finished fetching.



Deprecated

  • On get permission subscription state - [Deprecated] Callback trigger fires after the "Get permission subscription state" action has finished fetching.

Expressions

press to zoom

press to zoom

press to zoom
1/2

The following expression groups:

  • Status

  • Tags

  • Sending notifications

  • In-app messaging - Trigger

  • In-app messaging - Click

  • Email - Status

  • Subscription status

  • Permission status

  • Receiving notifications

  • User properties

  • Deprecated

Status

  • SubscriptionStatus - Returns the current notification subscription state, in JSON string.


  • PermissionStatus - Returns the current notification permission state, in JSON string.



Tags

  • Tags - Retrieves the list of tags in JSON string, this is for when the "On get tags" callback condition trigger fires.



Sending notifications

  • PostNotificationData - Returns the post notification response data, in JSON string.



In-app messaging - Trigger

  • TriggerValue - Returns a single trigger value for the given key if it exists, otherwise returns an empty string.



In-app messaging - Click

  • InAppMessageClickData - Returns the in-application message notification's click data, in JSON string.


  • FirstClick - Returns "True" if this is the first time the user has pressed any action on an in-app message, otherwise "False".


  • ClosesMessage - Did the action close the in-app message. Returns "True" if the in-app nessage will animate off the screen, otherwise "False" if the in-app message will stay on the screen until the user dismisses.


  • ClickURL - Returns an optional URL that opens when the action takes place. Only present if set through the dashboard.


  • ClickName - An optional click name defined for the action element. Only present if set through the dashboard.



Email - Status

  • NewEmail - Returns the new email address detected by the "Email status" observer.


  • NewEmailuserID - Returns the new user id detected by the "Email status" observer.


  • OldEmail - Returns the old email used before a change was detected by the "Email status" observer.


  • OldEmailUserID - Returns the old user id used before a change was detected by the "Email status" observer.



Subscription status

  • Subscribed - Returns "True" if subscribed to push notifications, otherwise "False".


  • UserID - Returns the user's identification in OneSignal.


  • PushToken - Returns the device identifier from FCM/APNs.



Permission status

  • Status - Returns either of the following integers: 0 = Not Determined, 1 = Denied, 2 = Authorized, 3 = Provisional and 4 = Ephemeral.


  • HasPrompted - Returns "False" if not prompted, or "True" if prompted.


  • Provisional - Returns either "True" or "False". [iOS only] Provisional notifications are non-interruptive notifications and can be turned on in the iOS Settings.



Receiving notifications

  • NotificationReceivedData - Returns the received notification's data, in JSON string.


  • NotificationOpenedData - Returns the opened notification's data, in JSON string.



User properties

  • DeviceState - Returns the fetched device state in JSON string, which is a response of the callback trigger "On get device state".



Deprecated

  • UserSubscriptionSetting - [Deprecated] Returns value of "Set Subscription". Defaults to "True".


  • ObserverPermissionStatus - [Deprecated] Returns the permission status observer data, in JSON string.


  • ObserverSubscriptionStatus - [Deprecated] Returns the subscription status observer data, in JSON string.


  • State - [Deprecated] Returns either of the following integers: 1 = Authorized and 2 = Denied.


  • NewUserID - [Deprecated] Returns the new user id detected by the "Email Status Observer".


  • OldUserID - [Deprecated] Returns the old user id used before a change was detected by the "Email Status Observer".

Object   Properties

Plugin Properties

press to zoom

press to zoom
1/1

The following property groups:

  • Configuration

  • Initialization

  • iOS Initialization

  • Privacy

  • Status

  • Data

  • Email

Configuration - The options to set the plugin settings.

  • Debug - Check to log information and messages including errors in the debug console.


  • App id - Your OneSignal application id (app id).



Initialization - The settings required to set before starting the OneSignal SDK and service.

  • Push Notifications - Check to allow receiving push notifications on startup. This is checked by default, you can toggle this during runtime by calling the action "Set push disabled".



Notification - The notifications configuration section.

  • Show foreground - Show notifications received in the application's foreground. [Recommended] to set checked.



Debug - The debugging configuration section for OneSignal.

  • Log level - Sets the logging level to print in Xcode or Android Studio.

  • 0 = NONE

  • 1 = FATAL

  • 2 = ERROR

  • 3 = WARN

  • 4 = INFO

  • 5 = DEBUG

  • 6 = VERBOSE


  • Visual level - Sets the logging level to show as alert dialogs.

  • 0 = NONE

  • 1 = FATAL

  • 2 = ERROR

  • 3 = WARN

  • 4 = INFO

  • 5 = DEBUG

  • 6 = VERBOSE



Privacy - The privacy settings for the users.

  • Requires user privacy consent - Allows the application to delay the initialization of the OneSignal SDK until the user provides privacy consent.



Status - The state of the notification subscriptions and permissions.

  • Permission status - If checked, the notification permission status is automatically updated when the observer detects a change.

  • Subscription status - If checked, the notification subscription status is observed and automatically updated when the observer detects a change.



Data - Configuration for the user's data.

  • Set location shared - Disable or enable location collection (defaults to enabled if your app has location permission).



Email - User email configuration section.

  • Email status - Check to enable the observer to track changes of email subscriptions (ie. the user sets their email or logs out).


 
 

Showcase