Unity SDK

📘

Just starting with Unity?

Check out our Unity SDK Setup guide.

Initialization

Settings

Settings that can be passed into the initialization chaining method.

Settings key options are:

• OneSignal.kOSSettingsAutoPrompt - Auto prompt user for notification permissions.
• OneSignal.kOSSettingsInAppLaunchURL - Launch notifications with a launch URL as an in app webview.

Privacy

SetRequiresUserPrivacyConsent

Allows you to delay the initialization of the SDK until the user provides privacy consent. The SDK will not be fully initialized until the UserDidProvideConsent(true) method is called. The SDK will remember the answer to the last time UserDidProvideConsent was called so you only need to call it once.

If you set this to be true, the SDK will not fully initialize until consent is provided. You can still call OneSignal methods, but nothing will happen, and the user will not be registered for push notifications.

void YourAppInitMethod() {
  // SetRequiresUserPrivacyConsent will prevent
  //   initialization until UserDidProvideConsent(true) is called
  OneSignal.StartInit("YOUR_APP_ID")
    .SetRequiresUserPrivacyConsent(true)
    .EndInit();
}

UserDidProvideConsent

If your application is set to require the user's privacy consent, you can provide this consent using this method. Until you call UserDidProvideConsent(true), the SDK will not fully initialize and will not send any data to OneSignal. The SDK will remember the answer to the last time UserDidProvideConsent was called so you only need to call it once.

void UserAcceptedConsent() {
   // Only needs to be called once,
   //   OneSignal will remember the last answer 
   OneSignal.UserDidProvideConsent(true);
}

UserProvidedConsent

Returns a boolean indicating if the user has given privacy consent yet.

Prompting

PromptForPushNotificationsWithUserResponse

Call this when you would like to prompt an iOS user to accept push notifications with the default system prompt. Only use if you passed false to autoRegister when calling Init.

OneSignal.PromptForPushNotificationsWithUserResponse(OneSignal_promptForPushNotificationsReponse);

private void OneSignal_promptForPushNotificationsReponse(bool accepted) {
  Debug.Log("OneSignal_promptForPushNotificationsReponse: " + accepted);
}

Status

GetPermissionSubscriptionState

Get the current notification and permission state. Returns a OSPermissionSubscriptionState type described below.

var status = OneSignal.GetPermissionSubscriptionState();
status.permissionStatus.hasPrompted;
status.permissionStatus.status;

status.subscriptionStatus.subscribed;
status.subscriptionStatus.userSubscriptionSetting;
status.subscriptionStatus.userId;
status.subscriptionStatus.pushToken;

permissionObserver

Delegate will be fired when a notification permission setting changes.
This includes the following events:

• Notification permission prompt shown. iOS
• The user accepting or declining the permission prompt iOS
• Enabling/disabling notifications for your app in the Device's Settings after returning to your app.

Example

Output is showings the user accepting the notification permission prompt.

OneSignal.permissionObserver += OneSignal_permissionObserver;

 private void OneSignal_permissionObserver(OSPermissionStateChanges stateChanges) {
       // Example of detecting anwsering the permission prompt
    if (stateChanges.from.status == OSNotificationPermission.NotDetermined) {
      if (stateChanges.to.status == OSNotificationPermission.Authorized)
         Debug.Log("Thanks for accepting notifications!");
      else if (stateChanges.to.status == OSNotificationPermission.Denied)
         Debug.Log("Notifications not accepted. You can turn them on later under your device settings.");
    }
   
    Debug.Log("stateChanges.to.status: " + stateChanges.to.status);
 }

subscriptionObserver

Delegate will be fired when a notification subscription property changes.

This includes the following events:

• Getting a push token from Apple or Google.
• Getting a player / user id from OneSignal
• OneSignal.setSubscription is called
• User disables or enables notifications

Example

OneSignal.subscriptionObserver += OneSignal_subscriptionObserver;

private void OneSignal_subscriptionObserver(OSSubscriptionStateChanges stateChanges) {
      Debug.Log("stateChanges: " + stateChanges);
      Debug.Log("stateChanges.to.userId: " + stateChanges.to.userId);
      Debug.Log("stateChanges.to.subscribed: " + stateChanges.to.subscribed);
   }

Tags

GetTags

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

void SomeMethod() {
        OneSignal.GetTags(TagsReceived);
    }

    private void TagsReceived(Dictionary<string, object> tags) {
        foreach (var tag in tags)
            print(tag.Key + ":" + tag.Value);
    }

TagsReceived

Delegate you can define to get the all the tags set on a player from onesignal.com.

private static void TagsReceived(Dictionary<string, object> tags) {
        foreach (var tag in tags)
            print(tag.Key + ":" + tag.Value);
    }

SendTag

Tag a player based on a game event of your choosing so later you can create segments on onesignal.com to target these players. If you need to set more than one key at a time please use SendTags instead.

OneSignal.SendTag("key", "value");

SendTags

Set multiple tags on a player with one call.

OneSignal.SendTags(new Dictionary<string, string>() { {"UnityTestKey2", "value2"}, {"UnityTestKey3", "value3"} });

DeleteTag

Deletes a tag that was previously set on a player with SendTag or SendTags. Please use DeleteTags if you need to delete more than one tag.

OneSignal.DeleteTag("key");

DeleteTags

Deletes tags that were previously set on a player with SendTag or SendTags.

OneSignal.DeleteTags(new List<string>() {"UnityTestKey2", "UnityTestKey3" })

Data

PromptLocation

Prompts the user for location permissions. This allows for geotagging so you can send notifications to users based on location.

OneSignal.PromptLocation();

SetLocationShared

Accepts a boolean parameter, allows you to enable or disable OneSignal SDK location tracking. Please note that if you disable location tracking, you will not be able to use location based push notifications.

//disables location features
OneSignal.SetLocationShared(false);

Receiving Notifications

PostNotification

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

using OneSignalPush.MiniJSON;

private static string oneSignalDebugMessage;

void someMethod() {
  // Just an example userId, use your own or get it the devices by using the GetPermissionSubscriptionState method
  string userId = "b2f7f966-d8cc-11e4-bed1-df8f05be55ba";

  var notification = new Dictionary<string, object>();
  notification["contents"] = new Dictionary<string, string>() { {"en", "Test Message"} };

  notification["include_player_ids"] = new List<string>() { userId };
  // Example of scheduling a notification in the future.
  notification["send_after"] = System.DateTime.Now.ToUniversalTime().AddSeconds(30).ToString("U");

  OneSignal.PostNotification(notification, (responseSuccess) => {
    oneSignalDebugMessage = "Notification posted successful with id: " + responseSuccess["id"];
  }, (responseFailure) => {
    oneSignalDebugMessage = "Notification failed to post:\n" + Json.Serialize(responseFailure);
  });


}

See the Create notification REST API POST call for a list of all possible options. Note: You can only use include_player_ids as a targeting parameter from your app. Other target options such as tags and included_segments require your OneSignal App REST API key which can only be used from your server.

Canceling a Notification

After creating the notification using postNotification you can save the notification "id" from the responseSuccess callback to use for canceling the push if required.

Using the API Cancel notification endpoint, you can use something like this to cancel that push if needed through the SDK.

string url = "https://onesignal.com/api/v1/notifications/" + notificationId.ToString() + "?app_id=" + appId;

WebRequest request = WebRequest.Create(url);
ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };
request.Method = "DELETE";
request.GetResponse();

ClearOneSignalNotifications

Removes all OneSignal app notifications from the Notification Shade.

OneSignal.ClearOneSignalNotifications();

SetSubscription

You can call this method 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);

setEmail

setEmail allows you to set the user's email address with the OneSignal SDK. We offer several overloaded versions of this method.

OneSignal.SetEmail("[email protected]");

If you have a backend server, we strongly recommend using Identity Verification with your users. Your backend can generate an email authentication token and send it to your app. The following code also includes callbacks:

string emailAuthToken = ""; //from your backend server

OneSignal.SetEmail("[email protected]", emailAuthToken, () => {
    //Successfully set email
}, (error) => {
    //Encountered error setting email
});

logoutEmail

If your app implements logout functionality, you can call logoutEmail to dissociate the email from the device:

OneSignal.LogoutEmail (() => {
    // Successfully logged out of email
}, (error) => {
    // Encountered error logging out of email
});

addEmailSubscriptionObserver

We have also added a new email subscription observer to track changes to email subscriptions (ie. the user sets their email or logs out). In order to subscribe to email subscription changes you can implement the following:

void Start() {
    OneSignal.emailSubscriptionObserver += OneSignal_emailSubscriptionObserver;
}

Now, whenever the email subscription changes, this method will be called:

private void OneSignal_emailSubscriptionObserver(OSEmailSubscriptionStateChanges stateChanges) {
    string newEmailAddress = stateChanges.to.emailAddress;
}

External ID's

setExternalUserId

If your system assigns unique identifiers to users, it can be annoying to have to also remember their OneSignal user ID's as well. To make things easier, OneSignal now allows you to set an external_id for your users. Simply call this method, pass in your custom user ID (as a string), and from now on when you send a push notification, you can use include_external_user_ids instead of include_player_ids.

string myCustomUniqueUserId = "something from my backend server";
  
OneSignal.SetExternalUserId(myCustomUniqueUserId);

removeExternalUserId

If your user logs out of your app and you would like to disassociate their custom user ID from your system with their OneSignal user ID, you will want to call this method.

//usually called after the user logs out of your app
OneSignal.RemoveExternalUserId();

Notification Events

NotificationReceived

Use to process a OneSignal notification that was just received while the app was in focus.

OneSignal.StartInit("b2f7f966-d8cc-11e4-bed1-df8f05be55ba")
  .HandleNotificationReceived(HandleNotificationReceived)
  .EndInit();

// Called when your app is in focus and a notificaiton is recieved.
// The name of the method can be anything as long as the signature matches.
// Method must be static or this object should be marked as DontDestroyOnLoad
private static void HandleNotificationReceived(OSNotification notification) {
  OSNotificationPayload payload = notification.payload;
  string message = payload.body;

  print("GameControllerExample:HandleNotificationReceived: " + message);
  print("displayType: " + notification.displayType);
  extraMessage = "Notification received with text: " + message;
}

NotificationOpened

Use to process a OneSignal notification the user just tapped on.

OneSignal.StartInit("b2f7f966-d8cc-11e4-bed1-df8f05be55ba")
  .HandleNotificationOpened(HandleNotificationOpened)
  .EndInit();

// Called when a notification is opened.
// The name of the method can be anything as long as the signature matches.
// Method must be static or this object should be marked as DontDestroyOnLoad
private static void HandleNotificationOpened(OSNotificationOpenedResult result) {
  OSNotificationPayload payload = result.notification.payload;
  Dictionary<string, string> additionalData = payload.additionalData;
  string message = payload.body;
  string actionID = result.action.actionID;
  
  print("GameControllerExample:HandleNotificationOpened: " + message);
  extraMessage = "Notification opened with text: " + message;

  if (additionalData != null) {
    if (additionalData.ContainsKey("discount")) {
      extraMessage = (string)additionalData["discount"];
      // Take user to your store.
    }
  }
  if (actionID != null) {
    // actionSelected equals the id on the button the user pressed.
    // actionSelected will equal "__DEFAULT__" when the notification itself was tapped when buttons were present.
    extraMessage = "Pressed ButtonId: " + actionID;
  }
}

OSNotificationOpenedResult

The information returned from a notification the user received.

OSNotification

The notification the user opened.

displayType

How the notification was displayed to the user. Part of OSNotification. See InFocusDisplaying for more information on how this is used.

Notification - native notification display.
InAppAlert (Default) - native alert dialog display.
None - notification is silent, or InFocusDisplaying is disabled.

OSNotificationAction

The action the user took on the notification.

OSNotificationPayload

Contents and settings of the notification the user received.

ActionButton

List of action buttons on the notification. Part of OSNotificationPayload.

BackgroundImageLayout

If a background image was set, this object will be available. Part of 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.

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.

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

OneSignal.EnableSound(false);

In-App Messaging

See Sending In-App Messages before getting started.

How do triggers work?

In-App Message triggers are handled by our SDK using the addTrigger or addTriggers method. A trigger is a key: value pair of string or integer data that you set programmatically in your app when an event occurs.

For example, if you want to send an IAM when a user reaches level 5 and level 10 of your game. Each time the use grows a level, you would call for example OneSignal.addTrigger("level", 1); then when they reach level 2, you simply update the trigger OneSignal.addTrigger("level", 2); and so on. At OneSignal.addTrigger("level", 5); you can then have the IAM show to the user by setting the key as level is 5 or level is greater than or equal to 5

Triggers are cleared each time the app is closed.

addTrigger

Add a trigger, may show an In-App Message if its triggers conditions were met.

Example

// Add a single trigger
OneSignal.AddTrigger("key", "value");

addTriggers

Add a map of triggers, may show an In-App Message if its triggers conditions were met.

removeTriggerForKey

Removes a single trigger for the given key, may show an In-App Message if its triggers conditions were met.

Example

// Delete a trigger
OneSignal.RemoveTriggerForKey("key");

removeTriggersForKeys

Removes a list of triggers based on a collection of keys, may show an In-App Message if its triggers conditions were met.

getTriggerValueForKey

Gets a trigger value for a provided trigger key.

Example

// Get the current value to a trigger by key
var triggerValue = OneSignal.GetTriggerValueForKey("key");

pauseInAppMessages

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.

HandleInAppMessageClicked

Sets a In App Message opened handler. The instance will be called when an In App Message action is tapped on.

Example

OneSignal.StartInit("YOUR_ONESIGNAL_APP_ID")
               .HandleInAppMessageClicked(HandleInAppMessageClicked)
               .EndInit();

InAppMessageClickHandler

Use to process an In App Message the user just tapped on.

Example

public static void HandleInAppMessageClicked(OSInAppMessageAction action) {
    String logInAppClickEvent = "In-App Message opened with action.clickName " + action.clickName;
    print(logInAppClickEvent);
    extraMessage = logInAppClickEvent;
}

OSInAppMessageAction

Details about the In App Message action element (button or image) that was tapped on.