Customizing Features

*Note:* WordPress users, customizing all of the features below can be found on the Configuration tab of our plugin. ## How do I hide the notify button after subscribing, or only show it on certain pages? The notify button init options takes in a `displayPredicate` function which is evaluated before the notify button is shown. To hide the notify button, this function must return the value `false` *or* a `Promise` that resolves to the value `false`. You may return any other value to show the notify button. Here is an example *hiding* the notify button if the user is subscribed: [block:code] { "codes": [ { "code": "// Do NOT call init() twice\n// This is just an example\nOneSignal.push([\"init\", {\n /* Your other init options here */\n notifyButton: {\n /* Your other notify button settings here ... */\n enable: true,\n displayPredicate: function() {\n return OneSignal.isPushNotificationsEnabled()\n .then(function(isPushEnabled) {\n /* The user is subscribed, so we want to return \"false\" to hide the notify button */\n return !isPushEnabled;\n });\n },\n }\n}]);", "language": "javascript" } ] } [/block] ## How do I customize or disable the automatic welcome notification when a new site visitor subscribes? Use the `welcomeNotification` parameter in your [init()](https://documentation.onesignal.com/docs/website-sdk-api#init) options. The `url` parameter is, by default, set to a special value that, on Chrome and Firefox, disables the notification from opening a separate webpage. By default, Safari must open a webpage and it will default to your site's URL. You may optionally set `url` so the notification opens a separate URL (on Chrome, Safari, and Firefox). **Showing a Welcome Notification** [block:code] { "codes": [ { "code": "// Do NOT call init() twice\nOneSignal.push([\"init\", {\n /* Your other init options here */\n welcomeNotification: {\n \"title\": \"My Custom Title\",\n \"message\": \"Thanks for subscribing!\",\n // \"url\": \"\" /* Leave commented for the notification to not open a window on Chrome and Firefox (on Safari, it opens to your webpage) */\n }\n}]);", "language": "javascript" } ] } [/block] **Disabling Welcome Notifications** [block:code] { "codes": [ { "code": "// Do NOT call init() twice\nOneSignal.push([\"init\", {\n welcomeNotification: {\n disable: true\n }\n}]);", "language": "javascript" } ] } [/block] ## How can I change the language / text of the subscription prompt pop-up window? [block:html] { "html": "<img src=\"http://i.imgur.com/v8I93BL.png\" style=\"background: url(http://i.imgur.com/v8I93BL.png) no-repeat 0 0;\tbackground-size: contain;\theight: auto;\tmax-width: 100%; margin: 0 auto; display: block;\"/>" } [/block] **Note**: This does not apply to Safari's permission prompt. This only applies to the HTTP prompt on Chrome and Firefox. Use the `promptOptions` parameter in your [init()](https://documentation.onesignal.com/docs/website-sdk-api#init) options. You may change all text except the URL on the notification image (subdomain.onesignal.com). You may enter text in your own language, but please note all fields are limited in length (usually to one line of text). Unset fields use their defaults. **Customizing the Pop-Up Text** [block:code] { "codes": [ { "code": "// Do NOT call init() twice\nOneSignal.push([\"init\", {\n // Your other init options here\n promptOptions: {\n /* Change bold title, limited to 30 characters */\n siteName: 'OneSignal Documentation',\n /* Subtitle, limited to 90 characters */\n actionMessage: \"We'd like to show you notifications for the latest news and updates.\",\n /* Example notification title */\n exampleNotificationTitle: 'Example notification',\n /* Example notification message */\n exampleNotificationMessage: 'This is an example notification',\n /* Text below example notification, limited to 50 characters */\n exampleNotificationCaption: 'You can unsubscribe anytime',\n /* Accept button text, limited to 15 characters */\n acceptButtonText: \"ALLOW\",\n /* Cancel button text, limited to 15 characters */\n cancelButtonText: \"NO THANKS\"\n }\n}]);", "language": "javascript" } ] } [/block] ## How can I enable or disable the notify button? How can I change the text or its behavior? Use the `notifyButton` parameter in your [init()](https://documentation.onesignal.com/docs/website-sdk-api#init) options. **Customizing the Notify Button** [block:code] { "codes": [ { "code": "// Do NOT call init() twice\nOneSignal.push([\"init\", {\n /* Your other init options here */\n notifyButton: {\n enable: true, /* Required to use the notify button */\n size: 'medium', /* One of 'small', 'medium', or 'large' */\n theme: 'default', /* One of 'default' (red-white) or 'inverse\" (white-red) */\n position: 'bottom-right', /* Either 'bottom-left' or 'bottom-right' */\n offset: {\n bottom: '0px',\n left: '0px', /* Only applied if bottom-left */\n right: '0px' /* Only applied if bottom-right */\n },\n prenotify: true, /* Show an icon with 1 unread message for first-time site visitors */\n showCredit: false, /* Hide the OneSignal logo */\n text: {\n 'tip.state.unsubscribed': 'Subscribe to notifications',\n 'tip.state.subscribed': \"You're subscribed to notifications\",\n 'tip.state.blocked': \"You've blocked notifications\",\n 'message.prenotify': 'Click to subscribe to notifications',\n 'message.action.subscribed': \"Thanks for subscribing!\",\n 'message.action.resubscribed': \"You're subscribed to notifications\",\n 'message.action.unsubscribed': \"You won't receive notifications again\",\n 'dialog.main.title': 'Manage Site Notifications',\n 'dialog.main.button.subscribe': 'SUBSCRIBE',\n 'dialog.main.button.unsubscribe': 'UNSUBSCRIBE',\n 'dialog.blocked.title': 'Unblock Notifications',\n 'dialog.blocked.message': \"Follow these instructions to allow notifications:\"\n }\n }\n}]);", "language": "javascript" } ] } [/block] **Customizing the Notify Button's Colors** You can override the theme's colors by entering your own. Values are strings which are then interpreted by CSS, so any CSS-valid color works as each value. For example, `white`, `#FFFFFF`, `#FFF`, `rgb(255, 255, 255)`, `rgba(255, 255, 255, 1.0)`, and `transparent` are all valid values. [block:code] { "codes": [ { "code": "// Do NOT call init() twice\nOneSignal.push([\"init\", {\n // Your other init options here\n notifyButton: {\n enable: true, // Required to use the notify button\n // Your other notify button settings here\n colors: { // Customize the colors of the main button and dialog popup button\n 'circle.background': 'rgb(84,110,123)',\n 'circle.foreground': 'white',\n 'badge.background': 'rgb(84,110,123)',\n 'badge.foreground': 'white',\n 'badge.bordercolor': 'white',\n 'pulse.color': 'white',\n 'dialog.button.background.hovering': 'rgb(77, 101, 113)',\n 'dialog.button.background.active': 'rgb(70, 92, 103)',\n 'dialog.button.background': 'rgb(84,110,123)',\n 'dialog.button.foreground': 'white'\n },\n }\n}]);", "language": "javascript" } ] } [/block] ## How can I automatically dismiss a notification after some time? On Firefox and Safari, notifications are automatically dismissed after a short amount of time. On Chrome, by default, notifications last indefinitely (they are displayed until the user interacts with it by dismissing it or clicking it). On Chrome Desktop v47+, you can add [the `persistNotification` parameter](doc:website-sdk-api#init) to your OneSignal init call to control whether a notification is displayed indefinitely or dismissed after 20 seconds. `persistNotification` defaults to true if unset. Set it to false to automatically dismiss the notification after 20 seconds (Chrome Desktop v47+ only). **Dismissing Notifications After ~20 Sec. (Chrome Desktop v47+)** [block:code] { "codes": [ { "code": "// Do NOT call init() twice\nOneSignal.push([\"init\", {\n // Your other init options here\n persistNotification: false // Automatically dismiss the notification after ~20 seconds in Chrome Deskop v47+\n}]);", "language": "javascript" } ] } [/block] ## Can manifest.json, OneSignalSDKWorker.js, and OneSignalSDKUpdaterWorker.js be served from a subfolder of my site? **manifest.json** - This file can be served from any subfolder of your site and the file can be named however you would like. Just be sure to include the file with the correct path and filename. - On Chrome, this files must still be served from your site (cannot be served from a CDN or another site). On Firefox and Safari, the manifest.json is not used for push notifications at all. **OneSignalSDKWorker.js & OneSIgnalSDKUpdaterWorker.js** - These files should not be renamed and the files should be served from the top-level root - Alternatively, these two files can be served from a sub-directory only if these two files are served with an additional HTTP header "Service-Worker-Allowed: /". These two files make up our service worker, a background web worker to display notifications. Parts of our web SDK depend on the service worker being registered properly: it should be served with the HTTP header "Service-Worker-Allowed: /" if served from a subfolder, otherwise it should be served at the top-level root of your site. If the files are served with the HTTP header "Service-Worker-Allowed: /", please add this code **before** initializing the SDK: [block:code] { "codes": [ { "code": "var OneSignal = OneSignal || [];\nOneSignal.push(function() {\n // Be sure to call this code *before* you initialize the web SDK\n \n // This registers the workers at the root scope, which is allowed by the HTTP header \"Service-Worker-Allowed: /\"\n OneSignal.SERVICE_WORKER_PARAM = { scope: '/' };\n});", "language": "javascript" } ] } [/block] If the files are served from a subfolder, please add this code **during** the initialization options so our SDK knows where to find the workers: [block:code] { "codes": [ { "code": "// Do NOT call init() twice\nOneSignal.push([\"init\", {\n // Your other init options here\n path: '/subfolder/', /* A trailing slash is required */\n}]);", "language": "javascript" } ] } [/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