Guides & Examples

[block:api-header] { "type": "basic", "title": "Subscribing Users With a Link" } [/block] Here is a simple example. It adds a link that, when clicked, prompts the user to subscribe to notifications. [block:code] { "codes": [ { "code": "<body>\n <a href=\"#\" id=\"subscribe-link\" style=\"display: none;\">Subscribe to Notifications</a>\n <script>\n function subscribe() {\n OneSignal.push([\"registerForPushNotifications\"]);\n event.preventDefault(); \n }\n \n var OneSignal = OneSignal || [];\n OneSignal.push(function() {\n document.getElementById(\"subscribe-link\").addEventListener('click', subscribe);\n document.getElementById(\"subscribe-link\").style.display = '';\n });\n </script>\n</body>", "language": "html" } ] } [/block] Here is a more complex example. A link is added that, when clicked, prompts the user to subscribe to notifications, but the link is shown only if the user is not subscribed, and notifications are supported. [block:code] { "codes": [ { "code": "<body>\n <a href=\"#\" id=\"subscribe-link\" style=\"display: none;\">Subscribe to Notifications</a>\n <script src=\"https://cdn.onesignal.com/sdks/OneSignalSDK.js\" async=\"async\"></script>\n <script>\n function subscribe() {\n OneSignal.push([\"registerForPushNotifications\"]);\n event.preventDefault();\n }\n\n var OneSignal = OneSignal || [];\n /* This example assumes you've already initialized OneSignal */\n OneSignal.push(function() {\n // If we're on an unsupported browser, do nothing\n if (!OneSignal.isPushNotificationsSupported()) {\n return;\n }\n OneSignal.isPushNotificationsEnabled(function(isEnabled) {\n if (isEnabled) {\n // The user is subscribed to notifications\n // Don't show anything\n } else {\n document.getElementById(\"subscribe-link\").addEventListener('click', subscribe);\n document.getElementById(\"subscribe-link\").style.display = '';\n }\n });\n });\n </script>\n</body>", "language": "html" } ] } [/block] [block:api-header] { "type": "basic", "title": "Tagging" } [/block] ## Tagging Users With Data OneSignal supports tagging users with simple string data. Once you've integrated web push on your website, you have access to all the [JavaScript web SDK API methods listed here](doc:website-sdk-api). Using JavaScript, you may tag your users with a key-value pair of simple string data at any time using the [sendTags() API method](https://documentation.onesignal.com/docs/website-sdk-api#sendTags). Here's an example of calling that: [block:code] { "codes": [ { "code": "OneSignal.push([\"sendTags\", {key2: \"value2\", key3: \"value3\"}]);", "language": "javascript" } ] } [/block] On your app's users page, you'll see the user with the tagged value: [block:image] { "images": [ { "image": [ "https://www.filepicker.io/api/file/ZuxRqS1xTdipWywmjfQn", "Rr5MHHy.png", "1412", "246", "#986b76", "" ] } ] } [/block] [block:callout] { "type": "warning", "title": "Tag Using Simple Strings Only", "body": "Don't tag users with arrays or hashes of data. Use only simple strings or numbers. We use exact string matching when targeting users by tags," } [/block] ## Sending Notifications to Specific Users There are two ways to send notifications: - Through our dashboard at onesignal.com - Programmatically using our REST API **Sending Notifications via the Dashboard** To target specific users, you have to first create a *Segment*. Add filters matching your key and value. [block:image] { "images": [ { "image": [ "https://www.filepicker.io/api/file/HJnu9UJmSpuQS4BEcDQh", "MiTf7bZ.png", "1428", "671", "#60afa3", "" ] } ] } [/block] [block:callout] { "type": "warning", "title": "Segment Filters Conditions are Combined", "body": "A segment includes all users that *matches all the filter conditions*. In other words the segment *AND*s filter conditions together, and does not *OR* filter conditions." } [/block] Please keep in mind that filter conditions are *combined* together to include users and are not evaluated separately! Now that you've created your segment matching at least one user, you can send send a notification targeting this segment using this option: [block:image] { "images": [ { "image": [ "https://www.filepicker.io/api/file/vIxD33kdSdu5s7gxF8Ae", "GjQkqeX.png", "1414", "642", "#5fb8b2", "" ] } ] } [/block] If you get an error saying "The selected segments does not have any users", go back to your Segments page and check the filter conditions. Remember they are *AND*ed together and not *OR*ed together. Make sure the segment includes at least one user. **Sending Notifications via the REST API** To send notifications programmatically via the API, use our [POST create notifications API](https://documentation.onesignal.com/docs/notifications-create-notification). To send notifications targeting users matching certain tags, use the tags parameter (check out the documentation). [block:api-header] { "type": "basic", "title": "Integrating With Existing User Data" } [/block] To link the subscribed user to your existing data, you can do one or more of the following: - You can [tag](#tagging) your user with a unique identifier from your system (e.g. your system's account email address) - You can store the user's OneSignal ID on your own system The first will associate our user with your user account ID on our system. The second will associate our user ID with your user info on your system. Please see the [tagging guide](#tagging) to learn how to tag your user with a unique identifier from your system. Please see below to learn how to store the user's OneSignal ID on your own system. ## Storing the OneSignal User ID Each subscribed user, corresponding to the user's phone that installs your Android app / iOS app or the user's browser that visited your website, has a unique and randomly generated OneSignal user ID. A OneSignal user ID looks like `b3aaabc2-9a47-4647-adda-3e4583a2d19e`. All of our IDs are [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier). For web push, you can obtain and send the OneSignal user ID to your server after the user subscribes to your website's notifications. We provide an event handler to be notified of when the user has successfully subscribed. Below is example code that waits for the user to subscribe, and then obtains the user's OneSignal ID: [block:code] { "codes": [ { "code": "OneSignal.push(function() {\n OneSignal.on('subscriptionChange', function(isSubscribed) {\n if (isSubscribed) {\n // The user is subscribed\n // Either the user subscribed for the first time\n // Or the user was subscribed -> unsubscribed -> subscribed\n OneSignal.getUserId( function(userId) {\n // Make a POST call to your server with the user ID\n });\n }\n });\n});", "language": "javascript" } ] } [/block] Once the OneSignal user ID is on your server, you can use our REST API to send notifications programmatically targeting just this user. You would use our [POST create notifications API](https://documentation.onesignal.com/docs/notifications-create-notification) and use the `include_player_ids` parameter and pass in an array of strings specifying the list of OneSignal user IDs you would like to target. [block:api-header] { "type": "basic", "title": "Switching your site between HTTP and HTTPS subscription method" } [/block] Read about [HTTP vs. HTTPS features here](doc:http-vs-https-features). [block:callout] { "type": "info", "title": "Upgrading Your Site to HTTPS", "body": "If you're looking for a free and easy way to add SSL to your site, you can use [CloudFlare's Flexible SSL option](https://support.cloudflare.com/hc/en-us/articles/200170516-How-do-I-add-SSL-to-my-site-). You don't need to buy an SSL certificate, but if you'd like to be [more secure](https://support.cloudflare.com/hc/en-us/articles/200170416-What-do-the-SSL-options-Off-Flexible-SSL-Full-SSL-Full-SSL-Strict-mean-) you can." } [/block] **WordPress Users**: Please follow this guide and then complete the extra steps at the bottom. ## HTTP → HTTPS [block:callout] { "type": "warning", "title": "Your Site Should Only Support HTTPS", "body": "If the HTTP version of your site is still accessible, you **should not** follow these steps below. The HTTPS method of subscription will not work for users visiting the HTTP version of your site. Your site will only work for HTTPS visitors.\n\nIf you're using CloudFlare, you can [forcefully redirect all HTTP visitors --> HTTPS](https://support.cloudflare.com/hc/en-us/articles/200170536-How-do-I-redirect-all-visitors-to-HTTPS-SSL-)." } [/block] 1. *Create a new app* for your HTTPS site following our [HTTPS web push setup guide](doc:website-sdk-installation). You *can* re-use your *Google Project Number* (you'll put this in your `manifest.json` as `gcm_sender_id`) and *Google Server API Key*. This prevents users from receiving duplicate notifications if they subscribed to notifications on both your HTTP and HTTPS site and you sent a message to all your users. Following our HTTPS web push setup guide, be sure to [update your site with the new initialization code](https://documentation.onesignal.com/docs/website-sdk-installation#3-include-and-initialize-the-sdk). There *should not* be a 'subdomain' parameter in your init code. 2. **WordPress Users Only:** Visit your WordPress admin panel, visit our plugin admin page, select the Configuration tab, and at the top under Account Settings enable "My site uses an HTTPS connection (SSL)". Replace your app ID if you created a new app. Now that your site is HTTPS, you'll see more options, including the ability to automatically prompt users to subscribe to notifications ("Automatically prompt new site visitors to subscribe to push notifications" under Prompt Settings & Notify Button). [block:api-header] { "type": "basic", "title": "Opening web and mobile notifications in the browser and app" } [/block] If you have web and mobile platforms users, you can send two notifications: the first notification to web browsers and the second notification to mobile phones. The web push notification will open in a web browser and the mobile push notification will open in your app. For the first notification sent to web push users, send the notification normally without specifically excluding any parameters. For the second notification sent to mobile users, *make sure to exclude* the `url` parameter. If the `url` parameter is included, a new browser tab will be opened to that URL. Instead, pass data in to the `additionalData` field (in a custom format your app will be able to parse), and then use the mobile notification opened / notification clicked handler to navigate the user to a section in your app. Here is [an example using native Android](http://stackoverflow.com/a/37935082/555547). Here is the documentation for the [native notificationOpened handler](https://documentation.onesignal.com/docs/android-sdk-api#section-notificationopenedhandler) used by the example. If you're using Cordova, Phonegap, or Ionic, be sure to [use the notificationOpened handler from the Cordova, Phonegap, or Ionic section of our docs](https://documentation.onesignal.com/docs/phonegap--cordova-sdk-api#notificationOpenedCallback). On the code example, be sure to click the variant describing how to open a page in your app. ## WordPress Users Only To take advantage of our WordPress plugin doing this for you, you will have to follow some additional instructions below to add a WordPress filter hook. 1. On our plugin's Configuration page, please *disable* the option "Send notifications additionally to iOS & Android platforms". This option does not allow customizing the mobile notifications so we have to disable this option first. 2. Copy and paste the PHP code below into a file that will get called when the notification gets sent out. A good candidate might be an "index" or "header" PHP file that will always get called. The goal is to add the below code to this file so that it will get called when our plugin sends out a WordPress notification. [block:code] { "codes": [ { "code": "<?php\nadd_filter('onesignal_send_notification', 'onesignal_send_notification_filter', 10, 4);\n\nfunction onesignal_send_notification_filter($fields, $new_status, $old_status, $post)\n{\n /* Goal: We don't want to modify the original $fields array, because we want the original web push notification to go out unmodified. However, we want to send an additional notification to Android and iOS devices with an additionalData property.\n */\n $fields_dup = $fields;\n $fields_dup['isAndroid'] = true;\n $fields_dup['isIos'] = true;\n $fields_dup['isAnyWeb'] = false;\n $fields_dup['isWP'] = false;\n $fields_dup['isAdm'] = false;\n $fields_dup['isChrome'] = false;\n $fields_dup['data'] = array(\n \"myappurl\" => $fields['url']\n );\n /* Important to unset the URL to prevent opening the browser when the notification is clicked */\n unset($fields_dup['url']);\n /* Send another notification via cURL */\n $ch = curl_init();\n $onesignal_post_url = \"https://onesignal.com/api/v1/notifications\";\n /* Hopefully OneSignal::get_onesignal_settings(); can be called outside of the plugin */\n $onesignal_wp_settings = OneSignal::get_onesignal_settings();\n $onesignal_auth_key = $onesignal_wp_settings['app_rest_api_key'];\n curl_setopt($ch, CURLOPT_URL, $onesignal_post_url);\n curl_setopt($ch, CURLOPT_HTTPHEADER, array(\n 'Content-Type: application/json',\n 'Authorization: Basic ' . $onesignal_auth_key\n ));\n curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n curl_setopt($ch, CURLOPT_HEADER, true);\n curl_setopt($ch, CURLOPT_POST, true);\n curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($fields_dup));\n curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);\n\n // Optional: Turn off host verification if SSL errors for local testing\n // curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);\n\n /* Optional: cURL settings to help log cURL output response\n curl_setopt($ch, CURLOPT_FAILONERROR, false);\n curl_setopt($ch, CURLOPT_HTTP200ALIASES, array(400));\n curl_setopt($ch, CURLOPT_VERBOSE, true);\n curl_setopt($ch, CURLOPT_STDERR, $out);\n */\n $response = curl_exec($ch);\n /* Optional: Log cURL output response\n fclose($out);\n $debug_output = ob_get_clean();\n $curl_effective_url = curl_getinfo($ch, CURLINFO_EFFECTIVE_URL);\n $curl_http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);\n $curl_total_time = curl_getinfo($ch, CURLINFO_TOTAL_TIME);\n onesignal_debug('OneSignal API POST Data:', $fields);\n onesignal_debug('OneSignal API URL:', $curl_effective_url);\n onesignal_debug('OneSignal API Response Status Code:', $curl_http_code);\n if ($curl_http_code != 200) {\n onesignal_debug('cURL Request Time:', $curl_total_time, 'seconds');\n onesignal_debug('cURL Error Number:', curl_errno($ch));\n onesignal_debug('cURL Error Description:', curl_error($ch));\n onesignal_debug('cURL Response:', print_r($response, true));\n onesignal_debug('cURL Verbose Log:', $debug_output);\n }\n\n */\n curl_close($ch);\n return $fields;\n}\n", "language": "php" } ] } [/block] [block:api-header] { "type": "basic", "title": "Customizing WordPress Plugin Behavior" } [/block] Our WordPress plugin comes with some [action and filter hooks](https://www.tipsandtricks-hq.com/wordpress-action-hooks-and-filter-hooks-an-introduction-4163) that allow you to write PHP code to extend our plugin's functionality. For example, our hooks can be used to: - Automatically check or uncheck the [meta box checkbox](http://i.imgur.com/xJ4BuSb.png) "Send notification on post publish" - You can use this to make it easier for content publishes to automatically send notifications for certain kind of posts - Always send a notification for certain post - (e.g. custom post types) - Never send a notification for certain posts - You can combine the include/exclude filter - Override any notification parameter, add extra parameters, remove extra parameters, and even send multiple notifications using the same call *Note:* For all the following example usage calls, you'll have to copy and paste the PHP code into a file that will always be called. A good candidate might be an "index" or "header" PHP file that will always get called. The goal is to add the below code to this file so that it will get called when our plugin takes the specified action. ## onesignal_meta_box_send_notification_checkbox_state Filter Overrides the state of the [meta box checkbox "Send notification on post publish"](http://i.imgur.com/xJ4BuSb.png). Example Usage: [block:code] { "codes": [ { "code": "<?php\nadd_filter('onesignal_meta_box_send_notification_checkbox_state', 'filter', 10, 4);\n// Available keys for $onesignal_wp_settings: https://github.com/OneSignal/OneSignal-WordPress-Plugin/blob/master/onesignal-settings.php#L5\nfunction filter($post, $onesignal_wp_settings) {\n // Always leave the checkbox \"Send notification on <post type> <action> (e.g. post publish)\" unchecked\n return false;\n} ", "language": "php" } ] } [/block] ## onesignal_include_post Filter Called every time a post's status changes as part of WordPress's [transition_post_status](https://codex.wordpress.org/Post_Status_Transitions#transition_post_status_Hook). Returning `true` will always send a notification for the specified post. Returning `false` does nothing; it simply passes control back to our main plugin logic. It's important to note returning `false` does not exclude the post -- that is done in the `onesignal_exclude_post` filter. You can use the `onesignal_include_post` and `onesignal_exclude_post` filter together. The order of operations is *INCLUDE -> EXCLUDE*. The `onesignal_include_post` filter is run first to determine whether a post is included. If a post is not included, the `onesignal_exclude_post` filter is run next to determine whether this post is excluded. If the post is not excluded, our normal plugin logic runs. Example Usage: [block:code] { "codes": [ { "code": "<?php\nadd_filter('onesignal_include_post', 'onesignal_include_post_filter', 10, 4);\nfunction onesignal_include_post_filter($new_status, $old_status, $post) {\n return false;\n}", "language": "php" } ] } [/block] ## onesignal_exclude_post Filter Called every time a post's status changes as part of WordPress's [transition_post_status](https://codex.wordpress.org/Post_Status_Transitions#transition_post_status_Hook). Returning `true` will never send a notification for the specified post. Returning `false` does nothing; it simply passes control back to our main plugin logic. It's important to note returning `false` does not include the post -- that is done in the `onesignal_include_post` filter. You can use the `onesignal_include_post` and `onesignal_exclude_post` filter together. The order of operations is *INCLUDE -> EXCLUDE*. The `onesignal_include_post` filter is run first to determine whether a post is included. If a post is not included, the `onesignal_exclude_post` filter is run next to determine whether this post is excluded. If the post is not excluded, our normal plugin logic runs. Example Usage: [block:code] { "codes": [ { "code": "<?php\nadd_filter('onesignal_exclude_post', 'onesignal_exclude_post_filter', 10, 4);\nfunction onesignal_exclude_post_filter($new_status, $old_status, $post) {\n return false;\n}", "language": "php" } ] } [/block] Example Usage: ## onesignal_send_notification Filter Called after all the notification creation parameters have been determined, and right before the notification is actually sent. You may modify any of the parameters to, for example: - Change the notification's title, message, and URL - Send the notification to additional platforms (e.g. Android and iOS) - Prevent the notification from being sent to certain platforms - Schedule the notification to be sent in the future - Add [action buttons](doc:web-push-action-buttons) - Cancel the notification from being sent Please see our [/notifications (Create Notification)](doc:notifications-create-notification) docs page for the full parameter list and description of what's accepted in the `$fields` hash. Example Usage: [block:code] { "codes": [ { "code": "<?php\nadd_filter('onesignal_send_notification', 'onesignal_send_notification_filter', 10, 4);\n\nfunction onesignal_send_notification_filter($fields, $new_status, $old_status, $post)\n{\n // Change the notification's title, message, and URL\n $fields['headings'] = array(\"en\" => \"English notification title\");\n $fields['contents'] = array(\"en\" => \"English notification message body\");\n $fields['url'] = 'https://example.com';\n \n // Send to additional platforms (e.g. Android and iOS)\n $fields['isAndroid'] = true;\n $fields['isIos'] = true;\n \n // Prevent the notification from being sent to certain platforms\n $fields['isFirefox'] = false;\n \n // Schedule the notification to be sent in the future\n $fields['send_after'] = \"Sept 24 2018 14:00:00 GMT-0700\";\n \n // Add web push action buttons (different action buttons are used for Android and iOS)\n $fields['web_buttons'] = array(\n \"id\" => \"like-button\",\n \"text\" => \"Like\",\n \"icon\" => \"http://i.imgur.com/N8SN8ZS.png\",\n \"url\" => \"https://example.com\"\n );\n \n // Cancel the notification from being sent\n $fields['do_send_notification'] = false;\n}", "language": "php" } ] } [/block]

OneSignal Push Notification Service Documentation

Introduction

iOS

Android

Amazon

Windows Phone

Chrome Apps/Extensions

Mac OS X

Website Push

Corona SDK

Unity SDK

Marmalade SDK

Adobe Air

PhoneGap, Cordova, Ionic

Xamarin SDK

React Native

Cocos2d-x

Server REST API

Troubleshooting

Miscellaneous