--- title: "Mobile App Integration Guide" slug: "mobile-app-integration-guide" description: "Mobile App SDK Integration in Insider One guides iOS and Android setup: SDK install, push certificates, push tests, user data, and Test Lab checks." updated: 2026-10-20T12:08:27Z published: 2026-10-20T12:08:27Z canonical: "academy.insiderone.com/mobile-app-integration-guide" --- > ## Documentation Index > Fetch the complete documentation index at: https://academy.insiderone.com/llms.txt > Use this file to discover all available pages before exploring further. # Mobile App Integration Guide Mobile App SDK Integration helps you connect your iOS and Android apps to Insider One through a guided, step-by-step flow in the Insider Onboarding Center. Your developers install the Insider One mobile SDK, configure push certificates, test app push and in-app messages, integrate your user data, verify it in the Test Lab, and set up the advanced features you use, all in one place. This enables accurate tracking of in-app user behavior and product interactions, which supports segmentation, personalization, analytics, and cross-channel engagement across mobile platforms. This guide walks you through every screen of Mobile App SDK Integration, explains what each choice means, and links to the detailed SDK documentation for each task. If this is your first mobile SDK integration, read it from top to bottom before you start. This guide covers the following topics: - [Before you start](/v1/docs/mobile-app-integration-guide#before-you-start) - [How the flow works](/v1/docs/mobile-app-integration-guide#how-the-flow-works) - [Step 1. Platform and feature selection](/v1/docs/mobile-app-integration-guide#step-1-platform-and-feature-selection) - [Step 2. Required setup](/v1/docs/mobile-app-integration-guide#step-2-required-setup) - [Step 3. Initialize SDK](/v1/docs/mobile-app-integration-guide#step-3-initialize-sdk) - [Step 4. Certificate configuration](/v1/docs/mobile-app-integration-guide#step-4-certificate-configuration) - [Step 5. Test push in the app](/v1/docs/mobile-app-integration-guide#step-5-test-push-in-the-app) - [Step 6. User data integration](/v1/docs/mobile-app-integration-guide#step-6-user-data-integration) - [Step 7. Test lab](/v1/docs/mobile-app-integration-guide#step-7-test-lab) - [Step 8. Advanced feature setup](/v1/docs/mobile-app-integration-guide#step-8-advanced-feature-setup) - [Good to know](/v1/docs/mobile-app-integration-guide#things-to-know) ## Before you start **Make sure you have the following before you open the flow:** - The Insider One user who will complete Mobile App SDK Integration has the **Administrator** role. - You have planned your user data in **User Data Planning** in the Insider Onboarding Center. - You know your partner name, which you can find at the top right of the InOne panel, next to your username. You use it in lowercase in your app code. - **For iOS:** a Mac with Xcode, access to your Apple Developer team with the App Manager role, a Debug or TestFlight build of your app, a real iPhone (push notifications are not delivered to the iOS Simulator), and a password manager to store your push key safely. - **For Android:** Android Studio, a Google account with access to Firebase, and a real Android device running Android 7.0 (API 24) or later. If you distribute your app on Huawei devices, you also need an AppGallery Connect account. > [!WARNING] > Make sure you complete Mobile App SDK Integration in your production account, not in your UAT account. ## How the flow works 1. Go to **Insider One** > **Insider Onboarding Center** > **User Data Integration** > **Mobile App SDK Integration**. 2. Read the overview page. It lists everything you will set up: platform and feature selection, required platform setup, SDK installation and initialization, push notifications, in-app messages, user data integration, and advanced features. 3. Click **Next** to start with Step 1. ![](https://cdn.document360.io/c6df4583-da94-4cb2-bb8a-be0cbdd11109/Images/Documentation/image-1792498089811.png) ## Step 1. Platform and feature selection In this step, you tell the flow which platforms your app runs on and which Insider One features you want to use. The rest of the flow, including code samples, configuration, and tests, adapts to your choices. ### Select your platforms 1. On the **Platform Selection** tab, select **iOS**, **Android**, or both under **Native Platforms**. 2. If your app also shows web pages inside a WebView and you want Insider One to work there too, select **iOS and Webview** or **Android and Webview** instead. You can't select **iOS** and **iOS and Webview** at the same time (the same applies to Android). 3. Click **Go To Feature Selection**. > [!NOTE] > **Note:** The step-by-step flow supports native iOS and Android apps. Support for React Native and Flutter is coming soon. If you select React Native, Flutter, or Cordova/Ionic, the flow shows a link to the Academy guide for that framework. ### Select your features 1. On the **Feature Selection** tab, review the list of features. Click a feature to see what it is, when to use it, how it works, and common technical pitfalls. 2. Keep the features you plan to use selected and uncheck the rest. Each selected feature adds a short setup and test to Step 8. Advanced Feature Setup. 3. Click **Next**. 4. The first time you continue, a **Feature Selection** confirmation appears. Check your selection, because it affects the next steps, and click **Continue**. | Feature | What it does | Developer guide | | --- | --- | --- | | **Geofence** | Sends push and in-app messages when a user enters, leaves, or stays in an area you define. | [iOS](https://academy.insiderone.com/docs/ios-start-tracking-geofence) · [Android](https://academy.insiderone.com/docs/android-start-tracking-geofence) | | **Smart Recommender** | Shows personalized product recommendations in your app. | [iOS](https://academy.insiderone.com/docs/ios-smart-recommender) · [Android](https://academy.insiderone.com/docs/android-smart-recommender) | | **App Cards** | Shows a persistent, swipeable feed of cards inside your app. | [iOS](https://academy.insiderone.com/docs/ios-configure-app-cards) · [Android](https://academy.insiderone.com/docs/android-configure-app-cards) | | **Social Proof** | Shows real-time signals, such as how many people viewed or bought a product. | Set up in the flow | | **Cart Reminder** | Sends push notifications about abandoned carts. | [iOS](https://academy.insiderone.com/docs/ios-cart-reminder) · [Android](https://academy.insiderone.com/docs/android-cart-reminder) | | **Content Optimizer** | Lets you A/B test content in your app without releasing a new version. | [iOS](https://academy.insiderone.com/docs/ios-content-optimizer) · [Android](https://academy.insiderone.com/docs/android-content-optimizer) | > [!WARNING] > Select Geofence only if your app genuinely uses location. Otherwise, your app might be rejected by the App Store, or Google Play might ask you to justify background location access. > [!NOTE] > A feature that is not included in your plan appears locked and can't be selected. To add it, contact your Account Director. > [!WARNING] > If you deselect a platform after you have started its setup, all integration progress for that platform is removed, including your answers, checklists, and test results. Uploaded certificates and test devices are kept. Deselecting a feature works the same way. In both cases, the flow asks you to confirm first. ![Platform and Feature Selection step in Mobile App SDK Integration](https://cdn.document360.io/c6df4583-da94-4cb2-bb8a-be0cbdd11109/Images/Documentation/image-1792410868950.png) ## Step 2. Required setup Before you install the SDK, you prepare your project so that your app can receive push notifications, rich push notifications with images and carousels, and links that open your app. Follow the part for your platform. ### Tell the flow about your push providers Before Required Setup, the flow asks a few questions about your app. Your answers change the instructions and code samples you see later. 1. For **Do you already have a push provider in your app?**, select **No, we only use Insider One** if Insider One is the only service that sends push notifications to your app. Select **Yes, we have one or more provider** if another service also sends push notifications to your app. 2. **Android only:** select **Google Play only**, or select **Huawei support needed** if you also distribute your app to Huawei devices that don't have Google Play Services. 3. Click **Next**. > [!WARNING] > If you change these answers later, the steps that depend on them (Required Setup and Initialize SDK, and Certificate Configuration for the Huawei answer) are reset and you need to complete them again. ### iOS: Required iOS setup This step prepares your Xcode project so that your app can receive push notifications, rich push notifications with images and carousels, and links that open your app. In Xcode, you add the two notification extensions Insider One needs (**InsiderNotificationService** and **InsiderNotificationContent**), turn on the required capabilities (**Push Notifications**, **Background Modes**, and **App Groups**), and add the Insider One URL scheme. The flow shows the instructions for each task. For details, see [iOS: Adding Required Targets](https://academy.insiderone.com/docs/ios-adding-required-targets) and [iOS: Capabilities and URL Types](https://academy.insiderone.com/docs/ios-capabilities-and-url-types). ![Required iOS Setup step in Mobile App SDK Integration](https://cdn.document360.io/c6df4583-da94-4cb2-bb8a-be0cbdd11109/Images/Documentation/image-1792410905585.png) ### Android: Required Android setup This step prepares your Android Studio project so that your app can receive push notifications. You add the Insider One SDK dependencies and your partner name to your Gradle files, add the required permissions to your manifest, and connect your app to Firebase Cloud Messaging (FCM), the Google service that delivers push notifications to Android devices. If you selected Huawei support, you also connect your app to Huawei Push Kit. The flow shows the instructions for each task. For details, see [Android: Required Dependencies and Permissions](https://academy.insiderone.com/docs/android-required-dependencies-and-permissions), [Android: Set Firebase Messaging Service](https://academy.insiderone.com/docs/android-set-firebase-messaging-service), and [Huawei Messaging Service](https://academy.insiderone.com/docs/huawei-messaging-service). ![Required Android Setup step in Mobile App SDK Integration](https://cdn.document360.io/c6df4583-da94-4cb2-bb8a-be0cbdd11109/Images/Documentation/image-1792410924993.png) ## Step 3. Initialize SDK In this step, add the Insider One SDK to your app and start it when your app launches so the SDK can collect data and receive messages. ### iOS You install the SDK with CocoaPods, Swift Package Manager, or Carthage, add the code shown in the flow to your two notification extensions, and add the initialization code to your AppDelegate with your partner name and App Group. The flow asks a few questions, for example, whether your app uses a SceneDelegate, and shows the code that matches your answers. For details, see [CocoaPods installation](https://academy.insiderone.com/docs/configure-cocoapods-installation), [SPM installation](https://academy.insiderone.com/docs/configure-swift-package-manager-spm-installation), [Carthage installation](https://academy.insiderone.com/docs/configure-carthage-installation), and [iOS: Initialize SDK](https://academy.insiderone.com/docs/ios-initialize-sdk). ### Android You add the initialization code shown in the flow to the onCreate method of your Application class, with your partner name in lowercase. If your app doesn't have an Application class yet, the flow shows you how to create one. For details, see [Android: Landing Class](https://academy.insiderone.com/docs/android-landing-class) and [Android: Initialize SDK](https://academy.insiderone.com/docs/android-initialize-sdk). ## Step 4. Certificate configuration To send push notifications to your app, Insider One needs permission from Apple (iOS) and Google (Android). In this step, you create these credentials and upload them to Insider One. ### iOS You create a push key (.p8) or a push certificate (.p12) on the Apple Developer website and upload it in the flow. A .p8 key never expires and works for all apps in your Apple Developer team. A .p12 certificate is created per app and expires every year. For a .p8 key, you also enter your Bundle ID, Key ID, and Team ID. For details, see [Apple Push Certificate (.p8)](https://academy.insiderone.com/docs/apple-push-certificate-p8) and [Apple Push Certificate (.p12)](https://academy.insiderone.com/docs/apple-push-certificate-p12). ### Android You create a Firebase service account key (a JSON file) in the Firebase console or the Google Cloud console and upload it in the flow. If you selected Huawei support, you also enter your Huawei Messaging Service App ID and App Secret. For details, see [Firebase Cloud Messaging API](https://academy.insiderone.com/docs/firebase-cloud-messaging-api) and [Huawei Messaging Service](https://academy.insiderone.com/docs/huawei-messaging-service). ![Certificate Configuration step in Mobile App SDK Integration](https://cdn.document360.io/c6df4583-da94-4cb2-bb8a-be0cbdd11109/Images/Documentation/image-1792410950199.png) ## Step 5. Test push in the app In this step, you check on a real device that your app receives push notifications and in-app messages. You run three tests: basic app push, advanced push, and in-app message. **Before you test, make sure you have:** - A real device: iOS 13 or later, or Android 7.0 or later. Push notifications are not delivered to the iOS Simulator. - A debug build of your app that includes everything from Steps 2 to 4. - Notifications allowed for your app on the device. - An internet connection on the device. ### Add a test device For details, see [Adding a Test Device on Mobile App](https://academy.insiderone.com/docs/adding-a-test-device-on-mobile-app). 1. Click **+ Create Test Device**. 2. Choose how to identify the device. With **Dynamic Link** (default), enter an email address you can open on the device and click **Send Email**. On the device, open the email from noreply@useinsider.com and tap the link to open your app. If the email doesn't arrive within 60 seconds, check your spam folder. 3. Alternatively, with **a QR Code**, run the debug build on the device, open the Insider One debugger in your app, tap **Pair Device**, and scan the QR code. 4. Go to the **Approve** tab, enter a name for the device (up to 60 characters), and click **Approve**. > [!NOTE] > If you can't add your device, open your app and complete one session, then close the app and try again. On iOS, check the URL scheme from Step 2. On Android, check the partner name in your Gradle file. For details, see [Why can't I add my device as a test device?](https://academy.insiderone.com/docs/why-cant-i-add-my-device-as-a-test-device). ### Test basic app push You test push notifications in three app states. The same device must receive all three. 1. Keep your app open on the device, click **Send Foreground Push**, select your test device, and send. **Test URL** and **Test Groups** are optional. 2. Put your app in the background (go to the home screen) and click **Send Background Push**. 3. Close your app completely (swipe it away) and click **Send Killed Push**. 4. Check the results table. The status must be **Delivered** for all three states on the same device. | Status | What it means | What to do | | --- | --- | --- | | **Delivered** | The push notification reached the device. | Continue with the next state. | | **Failed: Bad Device Token** | The app build and the certificate environment don't match. | Check that your certificate matches your build (development or production). | | **Failed: Device Token Not For Topic** | Your app's Bundle ID doesn't match the certificate. | Check the Bundle ID you entered in Step 4. | | **Failed: Unregistered** | The app was reinstalled or the device token is no longer valid. | Open the app again and add the device again if needed. | | **No device token** | Notifications aren't allowed for your app on the device. | Allow notifications in the device settings. | | **Mismatch Sender ID (Android)** | The service account key is from a different Firebase project. | Upload a key from the same project as your google-services.json file. | ### Test advanced push Advanced push opens after the basic push test is complete. 1. Send the advanced push in each app state. 2. Check that the images and carousel appear and that you can swipe through the cards. ### Test in-app message 1. Keep your app open on the device and click **Send In-App Message**. 2. Check that the message appears. The test is complete when the message is delivered to at least one device. ![Test push in the app step in Mobile App SDK Integration](https://cdn.document360.io/c6df4583-da94-4cb2-bb8a-be0cbdd11109/Images/Documentation/image-1792410983533.png) ## Step 6. User data integration In this step, you send information about who your users are and what they do in your app, so you can segment, personalize, and analyze. The flow shows the data you planned in User Data Planning, with ready-to-use code for each item. 1. On the overview page, review your user data. If your data plan is approved, you see a read-only list. If it isn't, select the data you want to integrate. Required items are selected for you and locked. 2. Open each page in the menu (identifiers, login and logout, attributes, and each event) and copy the code into the right place in your app, as described in the table below. 3. Open **User Data collected by Insider One** to see the data the SDK collects automatically. You don't need any code for this data. | Page | What it does | When to call it | Guide | | --- | --- | --- | --- | | **User Identifiers** | Tells Insider One who the user is, for example by email, phone number, or user ID. | When the user logs in, and every time a logged-in user opens the app. | [iOS](https://academy.insiderone.com/docs/ios-user-object) · [Android](https://academy.insiderone.com/docs/android-user-object) | | **Login & Logout** | Links the user's activity to their profile, or stops linking it. | Login: at sign-in and when a session is restored. Logout: only when the user signs out. | [iOS](https://academy.insiderone.com/docs/ios-user-object) · [Android](https://academy.insiderone.com/docs/android-user-object) | | **User Attributes** | Saves profile information such as name, language, opt-ins, and your custom attributes. | When the information becomes known or changes. | [iOS](https://academy.insiderone.com/docs/ios-user-object) · [Android](https://academy.insiderone.com/docs/android-user-object) | | **Events** | Records what the user does: home page, product page, listing page, cart, wishlist, purchase, sign-up confirmation, and your custom events. | At the moment, the action happens in your app. | [iOS](https://academy.insiderone.com/docs/ios-event-object) · [Android](https://academy.insiderone.com/docs/android-event-object) | ![User Data Integration step in Mobile App SDK Integration](https://cdn.document360.io/c6df4583-da94-4cb2-bb8a-be0cbdd11109/Images/Documentation/image-1792411002145.png) ## Step 7. Test lab In this step, you go to the Test Lab to check that every event and attribute from Step 6 reaches Insider One correctly. For details, see [Mobile App: Test Lab](https://academy.insiderone.com/docs/app-integration-test-lab). ![Test Lab step in Mobile App SDK Integration](https://cdn.document360.io/c6df4583-da94-4cb2-bb8a-be0cbdd11109/Images/Documentation/image-1792411015112.png) ## Step 8. Advanced feature setup In this step, you set up each feature you selected in Step 1. Before you start, make sure the SDK is initialized, your certificates are uploaded, and a real test device is available. **Each feature has its own page. On each page:** 1. On the **Configure** tab, follow the instructions and copy the code into your app. Click **Learn More** to read about the feature again. 2. On the **Test & Validate** tab, click **Connect Device** to connect your test device by dynamic link or QR code, and then follow the test. 3. When the test passes, the feature card changes from **Not Ready** to **Ready**, and you can create your first campaign for that feature. | Feature | What you set up | How you test it | | --- | --- | --- | | **Geofence** | Location permission and tracking after the SDK starts; optionally, background location. | Create a geofence in the panel, enter and leave the area with the app in the background, and check the location on the test device's user profile. | | **Smart Recommender** | User locale and product stock, where recommendations appear in your app, and click tracking. | Open product pages and confirm the data arrives. | | **App Cards** | Display cards, mark them as read, and handle their links. | Create an App Cards campaign and check that the cards appear in your app. | | **Social Proof** | The product page, home page, and listing page view events, or confirm they are already integrated. | Open product pages and confirm the views arrive. | | **Cart Reminder** | The item added to cart, item removed from cart, cart cleared, and purchase events. Push notifications must be allowed, and product images must use public HTTPS links. | Add an item to the cart and remove one, and check that both tests succeed. | | **Content Optimizer** | The content variables your app reads, and marking content as seen. | Check that the variables are registered, then create a Content Optimizer campaign. | > [!NOTE] > For Geofence, explain in your App Store review notes why your app needs location. On Google Play, you might need to declare background location access. ![Advanced Feature Setup step in Mobile App SDK Integration](https://cdn.document360.io/c6df4583-da94-4cb2-bb8a-be0cbdd11109/Images/Documentation/image-1792411047654.png) If you selected both iOS and Android, the flow continues with Android after the last iOS step. ## Good to know - Mobile App SDK Integration supports iOS and Android. For other frameworks, follow the [developer guide for mobile SDKs](https://academy.insiderone.com/docs/developer-guide-mobile-sdks). - Your progress is saved per step and shown in the side menu, so you can leave and continue later. - If you deselect a platform in Step 1, the progress for that platform is reset. After you complete the setup, your app is ready for app push and in-app campaigns in Insider One. ## Related - [Mobile App Integration Wizard](/app-integration-wizard.md) - [Push Certificates](/mobile-app-settings-push-certificates.md) - [Add a Test Device on Mobile App](/adding-a-test-device-on-mobile-app.md) - [FAQ about Test Devices](/faq-test-devices.md) - [Mobile App: Test Lab](/app-integration-test-lab.md)