Search specific term/phrase surrounded by double quotes. e.g. “deep linking”
Exclude records that contain a specific term prefixed with a minus. e.g. Android -Firebase
Guides
Submit a TicketBranch DashboardBranch Dashboard

mParticle iOS

Suggest Edits

This documentation explains how to send mParticle events to your Branch dashboard. If you'd like to send Branch installs to your mParticle dashboard, please review the Branch/mParticle Data Integration.

📘

These instructions apply to the mParticle SDK version 7+ integration

mParticle introduced a new attribution & deep linking API in v7 of their SDK (http://docs.mparticle.com/developers/sdk/ios/getting-started/#upgrade-to-version-7-of-the-sdk), so please contact your Branch or mParticle Account Managers for more details, if you have mParticle SDK < v7 installed in your app.

🚧

Inconsistent Universal links behavior on iOS 11.2

After updating a device to iOS 11.2, we found that the app's AASA file is no longer downloaded reliably onto your user’s device after an app install. As a result, clicking on Universal links will no longer open the app consistenly. You can set forced uri redirect mode on your Branch links to open the app with URI schemes. View details of the issue on the Apple Bug report.

Technical Requirements

📘

iOS 14 Implementation

In order to give you full control over the user experience, the Branch SDK will not trigger the IDFA permission modal.

However, we will still collect and use IDFAs when available if you do choose to trigger the modal.

LEARN MORE

Branch Setup

Configure bundle identifier

Confirm App Prefix

Configure Branch Dashboard & Enable Universal Links

Configure Associated Domains

  • Add your link domains from your Branch Dashboard
  • -alternate is needed for Universal Linking with the Web SDK inside your Website
  • test- is needed if you need use a test key
  • If you use a custom link domain, you will need to include your old link domain, your -alternate link domain, and your new link domain

Configure Entitlements

  • Confirm entitlements are within target

Configure info.pList

  • Add Branch Dashboard values

    • Add branch_app_domain with your live key domain
    • Add your URI scheme as URL Types -> Item 0 -> URL Schemes
    • Do NOT add your API keys to the file (mParticle handles this via the dashboard)

mParticle Setup

Enable Branch on mParticle

  • Before you can enable Branch in your mParticle dashboard, you must retrieve your Branch Key on the Link Settings page of your Branch dashboard.
  • Please follow mParticle's documentation on how to Connect an Event Output; i.e. enable the Branch integration.
  • If you have enabled Apple Search Ads for your Branch implementation, you must also check Enable Apple Search Ads in the Connection Settings.

Once you have added the kit and configured your branch API key in the mParticle dashboard, the mParticle SDKs will take care of initializing the Branch SDK and forwarding the appropriate application lifecycle events to handle deep links.

Install the mParticle Branch Kit

Option 1: CocoaPods

platform :ios, '8.0'

    target 'APP_NAME' do
      # if swift
      use_frameworks!

      ‘pod 'mParticle-BranchMetrics', '~> 8'
    end

Option 2: Carthage

github "mparticle-integrations/mparticle-apple-integration-branchmetrics"

Import iOS Support Libraries

  • AdSupport
  • SafariServices
  • MobileCoreServices
  • CoreSpotlight
  • iAd

Initializing Branch in the mParticle Kit

The mParticle iOS SDK (version 5.4.1 and later) will automatically call the following methods of the Branch Kit:

  • initSessionWithLaunchOptions: within application:didFinishLaunchingWithOptions:
  • handleDeepLink: within application:openURL:options:
  • continueUserActivity: within application:continueUserActivity:restorationHandler:

This means mParticle will automatically handle initializing Branch sessions. However, please ensure .onAttributionComplete is enabled in the mParticleOptions object.

🚧

mParticle appDelegate proxy not enabled

If the mParticle appDelegate proxy is not enabled, you must add mParticle's URI & Domain relays to the appDelegate.

At this point you should start seeing your Branch session data - including installs, re-opens, and any custom events - in your Branch dashboard.

Retrieve Deep Link Data via mParticle

Our integration with mParticle supports the creation and attribution of deep links to install and open an app. A deep link will typically contain some additional information to be used when the user ultimately opens your application, so that you can properly route the user to the appropriate content, or otherwise customize their experience.

Please ensure you've followed mParticle's documentation to ensure your deep link data is being retrieved.

📘

mParticle in React Native

If you integrate mParticle in React Native, you will still integrate the Branch kit as a Native module and follow the setup steps above. However, instead of retrieving deep link data in the the native layer, you'll retrieve deep link data via mParticle's React Native function found here.

NativeLink™ Deferred Deep Linking

  • Use iOS pasteboard to enable deferred deep linking via Branch NativeLink™

🚧

Prerequisite

Make sure the underlying iOS SDK Version is v1.39.4+

To use this feature you must:

Implement one of the pasteboard opt-in options in the native iOS SDK code.

Please note that deferred deep linking is part of our Engagement package. Learn more on our pricing page.

Test deep link

  • Create a deep link from the Branch Dashboard
  • Delete your app from the device
  • Compile and test on a device
  • Paste deep link in Apple Notes
  • Long press on the deep link (not 3D Touch)
  • Click Open in "APP_NAME"to open your app

Implementing Features

  • Please refer to mParticle's making direct calls to kits documentation for how to access the Branch kit via the mParticle SDK.
  • Once you have a reference to the Branch kit, refer to Branch's native iOS SDK documentation on how to implement secondary functionality.

Sample Testing Apps

Troubleshooting

Please refer to the Branch iOS SDK troubleshooting section.

Updated about 2 months ago