Merge pull request #2347 from OneSignal/docs/update_migration_guide_point_at_docs

nan-li · web-flow · commit d611cd2fc80f · 2025-08-06T17:35:54.000-07:00
diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md
@@ -30,22 +30,24 @@ OneSignal uses a built-in **alias label** called `external_id` which supports ex
 
 In Android Studio, open your `build.gradle.kts (Module: app)` or `build.gradle (Module: app)` file and update OneSignal in your `dependencies`.
 
-<CodeGroup>
-  ```kotlin app/build.gradle.kts
-  implementation("com.onesignal:OneSignal:[5.1.6, 5.1.99]")
-  ```
+```kotlin
+// in app/build.gradle.kts
 
-  ```groovy app/build.gradle
-  implementation 'com.onesignal:OneSignal:[5.1.6, 5.1.99]'
-  ```
-</CodeGroup>
+implementation("com.onesignal:OneSignal:[5.1.6, 5.1.99]")
+```
+
+```groovy
+// in app/build.gradle
+
+implementation 'com.onesignal:OneSignal:[5.1.6, 5.1.99]'
+```
 
 The above statement will bring in the entire OneSignalSDK and is the desired state for most integrations.  For greater flexibility you can alternatively specify individual modules that make up the full SDK.  The possible modules are:
 
-    `com.onesignal:core`: The required core module provided by the OneSignal SDK, this must be included.
-    `com.onesignal:notifications:` Include to bring in notification based functionality.
-    `com.onesignal:in-app-messages`: Include to bring in in app message functionality.
-    `com.onesignal:location`: Include to bring in location-based functionality.
+- `com.onesignal:core`: The required core module provided by the OneSignal SDK, this must be included.
+- `com.onesignal:notifications`: Include to bring in notification based functionality.
+- `com.onesignal:in-app-messages`: Include to bring in in app message functionality.
+- `com.onesignal:location`: Include to bring in location-based functionality.
 
 
 ## Code Modularization
@@ -71,8 +73,9 @@ In your `ApplicationClass`, initialize OneSignal with the provided methods.
 
 Replace `YOUR_APP_ID` with your OneSignal App ID found **Settings > [Keys & IDs](https://documentation.onesignal.com/docs/keys-and-ids)** in your OneSignal dashboard. If you don't have access to the OneSignal app, ask your [Team Members](https://documentation.onesignal.com/docs/manage-team-members) to invite you.
 
-<CodeGroup>
-```java Kotlin
+**Kotlin**
+
+```kotlin
 package com.your.package.name // Replace with your package name
 
 import android.app.Application
@@ -101,7 +104,9 @@ class ApplicationClass : Application() {
 
 ```
 
-```java Java
+**Java**
+
+```java
 package com.your.package.name // Replace with your package name
 
 import android.app.Application;
@@ -127,15 +132,14 @@ public class ApplicationClass extends Application {
 }
 
 ```
-</CodeGroup>
 
 If your integration is not user-centric, there is no additional startup code required.  A user is automatically created as part of the push subscription creation, both of which are only accessible from the current device and the OneSignal dashboard.
 
-If your integration is user-centric, or you want the ability to identify as the same user on multiple devices, the OneSignal SDK should be called once the user has been identified: [`OneSignal.login("USER_EXTERNAL_ID");`](https://documentation.onesignal.com/docs/mobile-sdk-reference#login-external-id)
+If your integration is user-centric, or you want the ability to identify as the same user on multiple devices, the OneSignal SDK should be called once the user has been identified: [`OneSignal.login("USER_EXTERNAL_ID")`](https://documentation.onesignal.com/docs/mobile-sdk-reference#login-external-id)
 
 The `login` method will associate the device’s push subscription to the user that can be identified via alias  `external_id`.  If a user with the provided `external_id` does not exist, one will be created.  If a user does already exist, the user will be updated to include the current device’s push subscription.  Note that a device's push subscription will always be transferred to the currently logged in user, as they represent the current owners of that push subscription.
 
-Once (or if) the user is no longer identifiable in your app (i.e. they logged out), the OneSignal SDK should be called: [`OneSignal.logout();`](https://documentation.onesignal.com/docs/mobile-sdk-reference#logout)
+Once (or if) the user is no longer identifiable in your app (i.e. they logged out), the OneSignal SDK should be called: [`OneSignal.logout()`](https://documentation.onesignal.com/docs/mobile-sdk-reference#logout)
 
 Logging out has the affect of reverting to a “device-scoped” user, which is the new owner of the device’s push subscription.
 
@@ -145,20 +149,22 @@ Logging out has the affect of reverting to a “device-scoped” user, which is
 In previous versions of the SDK there was a player that could have zero or one email address, and zero or one phone number for SMS.  In the user-centered model there is a user with the current device’s **Push Subscription** along with the ability to have zero or **more** email subscriptions and zero or **more** SMS subscriptions.  A user can also have zero or more push subscriptions, one push subscription for each device the user is logged into via the OneSignal SDK.
 
 **Push Subscription**
+
 The current device’s push subscription can be retrieved via: [`OneSignal.User.pushSubscription`](https://documentation.onesignal.com/docs/mobile-sdk-reference#user-pushsubscription-id)
 
 
-If at any point you want the user to stop receiving push notifications on the current device (regardless of Android permission status) you can use the push subscription to opt out: [`OneSignal.User.pushSubscription.optOut();`](https://documentation.onesignal.com/docs/mobile-sdk-reference#optout-%2C-optin-%2C-optedin)
+If at any point you want the user to stop receiving push notifications on the current device (regardless of Android permission status) you can use the push subscription to opt out: [`OneSignal.User.pushSubscription.optOut()`](https://documentation.onesignal.com/docs/mobile-sdk-reference#optout-%2C-optin-%2C-optedin)
 
 
-To resume receiving of push notifications (driving the native permission prompt if OS permissions are not available), you can opt back in: [`OneSignal.User.pushSubscription.optIn();`](https://documentation.onesignal.com/docs/mobile-sdk-reference#optout-%2C-optin-%2C-optedin)
+To resume receiving of push notifications (driving the native permission prompt if OS permissions are not available), you can opt back in: [`OneSignal.User.pushSubscription.optIn()`](https://documentation.onesignal.com/docs/mobile-sdk-reference#optout-%2C-optin-%2C-optedin)
 
 
-To observe changes to the push subscription a class can implement the IPushSubscriptionObserver interface, and can then be added as an observer: [`OneSignal.User.pushSubscription.addObserver(observer);`](https://documentation.onesignal.com/docs/mobile-sdk-reference#addobserver-push-subscription-changes)
+To observe changes to the push subscription a class can implement the IPushSubscriptionObserver interface, and can then be added as an observer: [`OneSignal.User.pushSubscription.addObserver(observer)`](https://documentation.onesignal.com/docs/mobile-sdk-reference#addobserver-push-subscription-changes)
 
 
 **Email/SMS Subscriptions**
-Email and/or SMS subscriptions can be added or removed via: [`OneSignal.User.addEmail("customer@company.com");`](https://documentation.onesignal.com/docs/mobile-sdk-reference#addemail-email) or [`OneSignal.User.addSms("+15558675309");`](https://documentation.onesignal.com/docs/mobile-sdk-reference#addsms-sms)
+
+Email and/or SMS subscriptions can be added or removed via: [`OneSignal.User.addEmail("customer@company.com")`](https://documentation.onesignal.com/docs/mobile-sdk-reference#addemail-email) or [`OneSignal.User.addSms("+15558675309")`](https://documentation.onesignal.com/docs/mobile-sdk-reference#addsms-sms)
 
 
 ## Kotlin-Related Changes
@@ -167,25 +173,25 @@ The OneSignal SDK has been rewritten in Kotlin. This is typically transparent to
 
 In Java this is surfaced on a method via an additional parameter to the method of type `Continuation`.  The `Continuation` is a callback mechanism which allows a Java function to gain control when execution has resumed.  If this concept is newer to your application codebase, OneSignal provides an optional java helper class to facilitate the callback model.  Method `com.onesignal.Continue.none()` can be used to indicate no callback is necessary:
 
-
-    OneSignal.getNotifications().requestPermission(true, Continue.none());
-
+```java
+OneSignal.getNotifications().requestPermission(true, Continue.none());
+```
 `com.onesignal.Continue.with()` can be used to create a callback lambda expression, which is passed a `ContinueResult` containing information on the success of the underlying coroutine, it's return data, and/or the exception that was thrown:
 
-```
-    OneSignal.getNotifications().requestPermission(true, Continue.with(r -> {
-        if (r.isSuccess()) {
-          if (r.getData()) {
-            // code to execute once requestPermission has completed successfully and the user has accepted permission.
-          }
-          else {
-            // code to execute once requestPermission has completed successfully but the user has rejected permission.
-          }
-        }
-        else {
-          // code to execute once requestPermission has completed unsuccessfully, `r.getThrowable()` might have more information as to the reason for failure.
-        }
-    }));
+```java
+OneSignal.getNotifications().requestPermission(true, Continue.with(r -> {
+    if (r.isSuccess()) {
+      if (r.getData()) {
+        // code to execute once requestPermission has completed successfully and the user has accepted permission.
+      }
+      else {
+        // code to execute once requestPermission has completed successfully but the user has rejected permission.
+      }
+    }
+    else {
+      // code to execute once requestPermission has completed unsuccessfully, `r.getThrowable()` might have more information as to the reason for failure.
+    }
+}));
 ```
 
 
