react-onesignal 2.0.0-beta1 → 2.0.3

package/MigrationGuide.md

@@ -0,0 +1,78 @@
+
+# Migration Guide
+Review the updated documentation in the [README](https://github.com/OneSignal/react-onesignal/blob/master/README.md).
+
+## Version 2
+Version 2.0 includes breaking changes. Make sure to follow this migration guide carefully, review the updated documentation, and test your application thoroughly.
+
+## Key Changes
+- Update your OneSignal initialization function (see below)
+- Remove the initialization hook (now handled for you automagically)
+- Event listeners are now set up using the `on` function
+- New functions supporting newer OneSignal features
+
+### OneSignal Initialization
+The initialization function has been changed to match 1:1 with the underlying OneSignal WebSDK. The function has been renamed `init`. The `appId` is now set via the single config options argument passed to the `init` function:
+
+```js
+import OneSignal from 'react-onesignal';
+
+OneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' });
+```
+
+Furthermore, there is no longer a need to wrap the initialization in the `useOneSignalSetup` hook. The order of functions relative to the OneSignal initialization no longer matters (although we still recommend initializing OneSignal in a top-level component).
+
+### Event Listeners
+Event listeners can now be added directly via the `on` function. This function takes an event string and a callback.
+
+### New Features
+We have added new functions to support the latest OneSignal functions and features.
+
+### Typings
+Typings are included in the package automatically. See below for a full list of the functions included in this package:
+```ts
+interface OneSignal {
+  init(options?: any): Promise<void>
+  on(event: string, listener: Function): void
+  off(event: string, listener: Function): void
+  once(event: string, listener: Function): void
+  isPushNotificationsEnabled(callback?: Action<boolean>): Promise<boolean>
+  showHttpPrompt(options?: AutoPromptOptions): void
+  registerForPushNotifications(options?: RegisterOptions): Promise<void>
+  setDefaultNotificationUrl(url: string): void
+  setDefaultTitle(title: string): void
+  getTags(callback?: Action<any>): void
+  sendTag(key: string,  value: any,  callback?: Action<Object>): Promise<Object | null>
+  sendTags(tags: TagsObject<any>,  callback?: Action<Object>): Promise<Object | null>
+  deleteTag(tag: string): Promise<Array<string>>
+  deleteTags(tags: Array<string>,  callback?: Action<Array<string>>): Promise<Array<string>>
+  addListenerForNotificationOpened(callback?: Action<Notification>): void
+  setSubscription(newSubscription: boolean): Promise<void>
+  showHttpPermissionRequest(options?: AutoPromptOptions): Promise<any>
+  showNativePrompt(): Promise<void>
+  showSlidedownPrompt(options?: AutoPromptOptions): Promise<void>
+  showCategorySlidedown(options?: AutoPromptOptions): Promise<void>
+  showSmsSlidedown(options?: AutoPromptOptions): Promise<void>
+  showEmailSlidedown(options?: AutoPromptOptions): Promise<void>
+  showSmsAndEmailSlidedown(options?: AutoPromptOptions): Promise<void>
+  getNotificationPermission(onComplete?: Function): Promise<NotificationPermission>
+  getUserId(callback?: Action<string | undefined | null>): Promise<string | undefined | null>
+  getSubscription(callback?: Action<boolean>): Promise<boolean>
+  setEmail(email: string,  options?: SetEmailOptions): Promise<string|null>
+  setSMSNumber(smsNumber: string,  options?: SetSMSOptions): Promise<string | null>
+  logoutEmail(): void
+  logoutSMS(): void
+  setExternalUserId(externalUserId: string | undefined | null,  authHash?: string): Promise<void>
+  removeExternalUserId(): Promise<void>
+  getExternalUserId(): Promise<string | undefined | null>
+  provideUserConsent(consent: boolean): Promise<void>
+  getEmailId(callback?: Action<string | undefined>): Promise<string | null | undefined>
+  getSMSId(callback?: Action<string | undefined>): Promise<string | null | undefined>
+  sendOutcome(outcomeName: string,  outcomeWeight?: number | undefined): Promise<void>
+}
+```
+
+## Summary
+Consider the above changes when migrating to version 2 and make sure to thoroughly test your application.
+
+Enjoy!

package/README.md

@@ -14,6 +14,9 @@ OneSignal is the world's leader for Mobile Push Notifications, Web Push, and In-
 
 You can find more information on OneSignal [here](https://onesignal.com/).
 
+### Migration Guide
+Version 2.0 was recently released. Read the [Migration Guide](https://github.com/OneSignal/react-onesignal/blob/master/MigrationGuide.md) here if you're coming from a version 1 release of the SDK.
+
 ## Contents
 - [Install](#install)
 - [Usage](#usage)
@@ -41,26 +44,26 @@ npm install --save react-onesignal
 ---
 ## Usage
 
-Initialize OneSignal with your app id:
+Initialize OneSignal with your `appId` via the `options` parameter:
 
 ```js
 import OneSignal from 'react-onesignal';
 
-OneSignal.initialize('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx');
+OneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' });
 ```
 
-The `initialize` function returns a promise that resolves when OneSignal is loaded.
+The `init` function returns a promise that resolves when OneSignal is loaded.
 
 **Examples**
 ```js
-await OneSignal.initialize('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx');
+await OneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' });
 // do other stuff
 ```
 ---
 
 ```js
 const [initialized, setInitialized] = useState(false);
-OneSignal.initialize('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx').then(() => {
+OneSignal.init({ appId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' }).then(() => {
   setInitialized(true);
   OneSignal.showSlidedownPrompt().then(() => {
     // do other stuff
@@ -68,51 +71,38 @@ OneSignal.initialize('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx').then(() => {
 })
 ```
 
-### Options
-You can pass an `options` object as the second parameter to the `initialize` function.
+### Init Options
+You can pass other [options](https://documentation.onesignal.com/docs/web-push-sdk#init) to the `init` function. Use these options to configure personalized prompt options, auto-resubscribe, and more.
 
-Where options are:
+**Service Worker Params**
+You can customize the location and filenames of service worker assets. You are also able to specify the specific scope that your service worker should control. You can read more [here](https://documentation.onesignal.com/docs/onesignal-service-worker-faq#sdk-parameter-reference-for-service-workers).
 
-```ts
-interface Options {
-  safari_web_id?: string;
-  subdomainName?: string;
-  allowLocalhostAsSecureOrigin?: boolean;
-  requiresUserPrivacyConsent?: boolean;
-  persistNotification?: boolean;
-  autoResubscribe?: boolean;
-  autoRegister?: boolean;
-  notificationClickHandlerMatch?: string;
-  notificationClickHandlerAction?: string;
-  notifyButton?: {
-    enable?: boolean;
-    size?: 'small' | 'medium' | 'large';
-    position?: 'bottom-left' | 'bottom-right';
-    showCredit?: boolean;
-    prenotify?: boolean;
-      theme?: 'default' | 'inverse';
-      offset?: {
-        bottom?: string;
-        right?: string;
-        left?: string;
-      },
-      text?: {
-        [key: string]: string;
-      };
-      colors?: {
-        [key: string]: string;
-      };
-  }
-}
-```
+In this distribution, you can specify the parameters via the following:
+
+| Field                      | Details                                                                                                                |
+|----------------------------|------------------------------------------------------------------------------------------------------------------------|
+| `serviceWorkerParam`       | Use to specify the scope, or the path the service worker has control of.  Example:  `{ scope: "/js/push/onesignal/" }` |
+| `serviceWorkerPath`        | The path to the service worker file.                                                                                   |
+
+### Service Worker File
+If you haven't done so already, you will need to add the [OneSignal Service Worker file](https://github.com/OneSignal/OneSignal-Website-SDK/files/7585231/OneSignal-Web-SDK-HTTPS-Integration-Files.zip) to your site ([learn more](https://documentation.onesignal.com/docs/web-push-quickstart#step-6-upload-files)).
+
+The OneSignal SDK file must be publicly accessible. You can put them in your top-level root or a subdirectory. However, if you are placing the file not on top-level root make sure to specify the path via the service worker params in the init options (see section above).
+
+**Tip:**
+Visit `https://yoursite.com/OneSignalSDKWorker.js` in the address bar to make sure the files are being served successfully.
 
 ---
 ## OneSignal API
-See the [OneSignal Web SDK reference](https://documentation.onesignal.com/docs/web-push-sdk) for more info.
+### Typescript
+This package includes Typescript support.
 
 ```ts
 interface OneSignal {
-  initialize(appId: string, options?: any, events?: Array<IOneSignalEvent>): Promise<void>
+  init(options?: any): Promise<void>
+  on(event: string, listener: Function): void
+  off(event: string, listener: Function): void
+  once(event: string, listener: Function): void
   isPushNotificationsEnabled(callback?: Action<boolean>): Promise<boolean>
   showHttpPrompt(options?: AutoPromptOptions): void
   registerForPushNotifications(options?: RegisterOptions): Promise<void>
@@ -152,58 +142,19 @@ interface OneSignal {
 ### OneSignal API
 See the official [OneSignal WebSDK reference](https://documentation.onesignal.com/docs/web-push-sdk) for information on all available SDK functions.
 
-### Typescript
-This package includes Typescript support.
-
 ---
 ## Advanced Usage
 ### Events and Event Listeners
 You can also listen for native OneSignal events like `subscriptionChange`.
 
-To add an event listener to the `OneSignal.push()` array, pass an array of events to the `initialize()` function as the third parameter.
-
-Each object in the array should contain:
-* `listener` -- (optional) Default value: `'on'`.
-Some events can be listened for via multiple listeners (e.g. `.on()`, `.once()`).
-[Check the docs](https://documentation.onesignal.com/docs/web-push-sdk) to see which listeners listen for your event.
-Example: `'on'` | `'once'`
-
-* `event` -- Name of the event being listened for.
-Example: `'subscriptionChange'`
-
-* `callback` -- Callback function for event.
-Example: `(value) => { console.log(value); }`
-
-For documentation on events and event listeners, check out the [Web Push SDK docs](https://documentation.onesignal.com/docs/web-push-sdk).
-
-```js
-const events = [
-  {
-    listener: 'once',
-    event: 'subscriptionChange',
-    callback: (isSubscribed) => {
-      if (true === isSubscribed) {
-        console.log('The user subscription state is now:', isSubscribed);
-      }
-    },
-  },
-  {
-    event: 'notificationDisplay',
-    callback: (event) => {
-      console.warn('OneSignal notification displayed:', event);
-    },
-  },
-  {
-    event: 'notificationDismiss',
-    callback: (event) => {
-      console.warn('OneSignal notification dismissed:', event);
-    },
-  },
-];
-
-
-OneSignal.initialize(applicationId, options, events);
+**Example**
 ```
+OneSignal.on('subscriptionChange', function(isSubscribed) {
+  console.log("The user's subscription state is now:", isSubscribed);
+});
+```
+
+See the [OneSignal WebSDK Reference](https://documentation.onesignal.com/docs/web-push-sdk) for all available event listeners.
 
 ---
 ## Thanks

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+declare type Action<T> = (item: T) => void;
+interface AutoPromptOptions {
+    force?: boolean;
+    forceSlidedownOverNative?: boolean;
+    slidedownPromptOptions?: IOneSignalAutoPromptOptions;
+}
+interface RegisterOptions {
+    modalPrompt?: boolean;
+    httpPermissionRequest?: boolean;
+    slidedown?: boolean;
+    autoAccept?: boolean;
+}
+interface SetSMSOptions {
+    identifierAuthHash?: string;
+}
+interface SetEmailOptions {
+    identifierAuthHash?: string;
+    emailAuthHash?: string;
+}
+interface TagsObject<T> {
+    [key: string]: T;
+}
+interface IOneSignalAutoPromptOptions {
+    force?: boolean;
+    forceSlidedownOverNative?: boolean;
+    isInUpdateMode?: boolean;
+    categoryOptions?: IOneSignalCategories;
+}
+interface IOneSignalCategories {
+    positiveUpdateButton: string;
+    negativeUpdateButton: string;
+    savingButtonText: string;
+    errorButtonText: string;
+    updateMessage: string;
+    tags: IOneSignalTagCategory[];
+}
+interface IOneSignalTagCategory {
+    tag: string;
+    label: string;
+    checked?: boolean;
+}
+interface IInitObject {
+    appId: string;
+    subdomainName?: string;
+    requiresUserPrivacyConsent?: boolean;
+    promptOptions?: object;
+    welcomeNotification?: object;
+    notifyButton?: object;
+    persistNotification?: boolean;
+    webhooks?: object;
+    autoResubscribe?: boolean;
+    autoRegister?: boolean;
+    notificationClickHandlerMatch?: string;
+    notificationClickHandlerAction?: string;
+    serviceWorkerParam?: {
+        scope: string;
+    };
+    serviceWorkerPath?: string;
+    serviceWorkerUpdaterPath?: string;
+    path?: string;
+    allowLocalhostAsSecureOrigin?: boolean;
+    [key: string]: any;
+}
+interface IOneSignal {
+    init(options: IInitObject): Promise<void>;
+    on(event: string, listener: () => void): void;
+    off(event: string, listener: () => void): void;
+    once(event: string, listener: () => void): void;
+    isPushNotificationsEnabled(callback?: Action<boolean>): Promise<boolean>;
+    showHttpPrompt(options?: AutoPromptOptions): Promise<void>;
+    registerForPushNotifications(options?: RegisterOptions): Promise<void>;
+    setDefaultNotificationUrl(url: string): Promise<void>;
+    setDefaultTitle(title: string): Promise<void>;
+    getTags(callback?: Action<any>): Promise<void>;
+    sendTag(key: string, value: any, callback?: Action<Object>): Promise<Object | null>;
+    sendTags(tags: TagsObject<any>, callback?: Action<Object>): Promise<Object | null>;
+    deleteTag(tag: string): Promise<Array<string>>;
+    deleteTags(tags: Array<string>, callback?: Action<Array<string>>): Promise<Array<string>>;
+    addListenerForNotificationOpened(callback?: Action<Notification>): Promise<void>;
+    setSubscription(newSubscription: boolean): Promise<void>;
+    showHttpPermissionRequest(options?: AutoPromptOptions): Promise<any>;
+    showNativePrompt(): Promise<void>;
+    showSlidedownPrompt(options?: AutoPromptOptions): Promise<void>;
+    showCategorySlidedown(options?: AutoPromptOptions): Promise<void>;
+    showSmsSlidedown(options?: AutoPromptOptions): Promise<void>;
+    showEmailSlidedown(options?: AutoPromptOptions): Promise<void>;
+    showSmsAndEmailSlidedown(options?: AutoPromptOptions): Promise<void>;
+    getNotificationPermission(onComplete?: Action<NotificationPermission>): Promise<NotificationPermission>;
+    getUserId(callback?: Action<string | undefined | null>): Promise<string | undefined | null>;
+    getSubscription(callback?: Action<boolean>): Promise<boolean>;
+    setEmail(email: string, options?: SetEmailOptions): Promise<string | null>;
+    setSMSNumber(smsNumber: string, options?: SetSMSOptions): Promise<string | null>;
+    logoutEmail(): Promise<void>;
+    logoutSMS(): Promise<void>;
+    setExternalUserId(externalUserId: string | undefined | null, authHash?: string): Promise<void>;
+    removeExternalUserId(): Promise<void>;
+    getExternalUserId(): Promise<string | undefined | null>;
+    provideUserConsent(consent: boolean): Promise<void>;
+    getEmailId(callback?: Action<string | undefined>): Promise<string | null | undefined>;
+    getSMSId(callback?: Action<string | undefined>): Promise<string | null | undefined>;
+    sendOutcome(outcomeName: string, outcomeWeight?: number | undefined): Promise<void>;
+    [index: string]: Function;
+}
+declare const OneSignalReact: IOneSignal;
+export default OneSignalReact;