Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Migration guide fixes post 5.0.0 release #1541

Merged
merged 6 commits into from
Sep 27, 2023
Merged

Migration guide fixes post 5.0.0 release #1541

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ccbf17b
Fix migration guide table formatting
nan-li Aug 21, 2023
f1fac3e
Update migration instructions for iOS
jennantilla Aug 21, 2023
a95127e
Change scope for login/logout method
jennantilla Aug 21, 2023
4c773f8
Fix formatting on NSE changes instructions
jennantilla Aug 22, 2023
ba42928
Remove NotificationService file updates
jennantilla Aug 22, 2023
4189a99
Misc migration guide updates
nan-li Aug 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
34 changes: 27 additions & 7 deletions MIGRATION_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,26 @@ OneSignal uses a built-in **alias label** called `external_id` which supports ex

# Migration Guide (v3 to v5)

The React Native SDK accesses the OneSignal native iOS and Android SDKs. For this update, all SDK versions are aligning across OneSignal’s suite of client SDKs. As such, the React Native SDK is making the jump from `v3` to `v5`.
The React Native SDK accesses the OneSignal native iOS and Android SDKs. For this update, all SDK versions are aligning across OneSignal’s suite of client SDKs. As such, the React Native SDK is making the jump from `v3` to `v5`. See existing install instructions [here](https://documentation.onesignal.com/docs/react-native-sdk-setup) for more information.

## iOS
### Notification Service Extension Changes

In your Project Root > ios > Podfile, update the notification service extension:

```
// 3.x.x
target 'OneSignalNotificationServiceExtension' do
pod 'OneSignalXCFramework', '>= 3.0', '< 4.0'
end

// 5.x.x
target 'OneSignalNotificationServiceExtension' do
pod 'OneSignalXCFramework', '>= 5.0', '< 6.0'
end
```

Close Xcode. While still in the ios directory, run `pod install --repo-update`.

# API Changes

Expand Down Expand Up @@ -71,15 +90,15 @@ If your integration is **not** user-centric, there is no additional startup code
If your integration is user-centric, or you want the ability to identify the user beyond the current device, the `login` method should be called to identify the user:

```typescript
OneSignal.User.login('USER_EXTERNAL_ID');
OneSignal.login('USER_EXTERNAL_ID');
```

The `login` method will associate the device’s push subscription to the user that can be identified via the alias `externalId=USER_EXTERNAL_ID`. If that user doesn’t already exist, it will be created. If the user does already exist, the user will be updated to own the device’s push subscription. Note that the push subscription for the device will always be transferred to the newly logged in user, as that user is the current owner of that push subscription.

Once (or if) the user is no longer identifiable in your app (i.e. they logged out), the `logout` method should be called:

```typescript
OneSignal.User.logout();
OneSignal.logout();
```

Logging out has the affect of reverting to a device-scoped user, which is the new owner of the device’s push subscription.
Expand Down Expand Up @@ -145,8 +164,8 @@ The SDK is still accessible via a `OneSignal` static class. It provides access t
| **React Native** | **Description** |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OneSignal.initialize("YOUR_ONESIGNAL_APP_ID")` | _Initializes the OneSignal SDK. This should be called during startup of the application._ |
| `OneSignal.User.login("USER_EXTERNAL_ID")` | _Login to OneSignal under the user identified by the [externalId] provided. The act of logging a user into the OneSignal SDK will switch the [user] context to that specific user.<br><br> - If the [externalId] exists, the user will be retrieved and the context will be set from that user information. If operations have already been performed under a device-scoped user, they **_will not_** be applied to the now logged in user (they will be lost).<br> - If the [externalId] does not exist the user, the user will be created and the context set from the current local state. If operations have already been performed under a device-scoped user, those operations **_will_** be applied to the newly created user.<br><br>**_Push Notifications and In App Messaging_**<br>Logging in a new user will automatically transfer the push notification and in app messaging subscription from the current user (if there is one) to the newly logged in user. This is because both push notifications and in-app messages are owned by the device._ |
| `OneSignal.User.logout()` | _Logout the user previously logged in via [login]. The [user] property now references a new device-scoped user. A device-scoped user has no user identity that can later be retrieved, except through this device as long as the app remains installed and the app data is not cleared._ |
| `OneSignal.login("USER_EXTERNAL_ID")` | _Login to OneSignal under the user identified by the [externalId] provided. The act of logging a user into the OneSignal SDK will switch the [user] context to that specific user.<br><br> - If the [externalId] exists, the user will be retrieved and the context will be set from that user information. If operations have already been performed under a device-scoped user, they **_will not_** be applied to the now logged in user (they will be lost).<br> - If the [externalId] does not exist the user, the user will be created and the context set from the current local state. If operations have already been performed under a device-scoped user, those operations **_will_** be applied to the newly created user.<br><br>**_Push Notifications and In App Messaging_**<br>Logging in a new user will automatically transfer the push notification and in app messaging subscription from the current user (if there is one) to the newly logged in user. This is because both push notifications and in-app messages are owned by the device._ |
| `OneSignal.logout()` | _Logout the user previously logged in via [login]. The [user] property now references a new device-scoped user. A device-scoped user has no user identity that can later be retrieved, except through this device as long as the app remains installed and the app data is not cleared._ |
| `OneSignal.setConsentGiven(true)` | _Indicates whether privacy consent has been granted. This field is only relevant when the application has opted into data privacy protections. See [requiresPrivacyConsent]._ |
| `OneSignal.setConsentRequired(true)` | _Determines whether a user must consent to privacy prior to their user data being sent up to OneSignal. This should be set to `true` prior to the invocation of `initialize` to ensure compliance._

Expand Down Expand Up @@ -237,10 +256,11 @@ The Session namespace is accessible via `OneSignal.Session` and provides access

The Notifications namespace is accessible via `OneSignal.Notifications` and provides access to notification-scoped functionality.

| **React Native** | **Description** |
| **React Native** | **Description** |
|--------------------------------------- | --------------- |
| `await OneSignal.Notifications.hasPermission()` | _Whether this app has push notification permission._ |
| `await OneSignal.Notifications.canRequestPermission()` | _Whether attempting to request notification permission will show a prompt. Returns `true` if the device has not been prompted for push notification permission already._ | `await OneSignal.Notifications.permissionNative()` | _(ios only) Returns the enum for the native permission of the device. It will be one of: NotDetermined, Denied, Authorized, Provisional (only available in iOS 12), Ephemeral (only available in iOS 14) _ |
| `await OneSignal.Notifications.canRequestPermission()` | _Whether attempting to request notification permission will show a prompt. Returns `true` if the device has not been prompted for push notification permission already._ |
| `await OneSignal.Notifications.permissionNative()` | _(ios only) Returns the enum for the native permission of the device. It will be one of: NotDetermined, Denied, Authorized, Provisional (only available in iOS 12), Ephemeral (only available in iOS 14)_ |
| `OneSignal.Notifications.clearAll();` | _Removes all OneSignal notifications._ |
| `OneSignal.Notifications.removeNotification(32432)` | _(Android only) Cancels a single OneSignal notification based on its Android notification integer ID. Use instead of Android's [android.app.NotificationManager.cancel], otherwise the notification will be restored when your app is restarted._ |
| `OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY")` | _(Android only) Cancels a group of OneSignal notifications with the provided group key. Grouping notifications is a OneSignal concept, there is no [android.app.NotificationManager] equivalent._ |
Expand Down