Skip to content

Pimmr/react-native-branch-deep-linking

 
 

Repository files navigation

Branch Metrics React Native SDK Reference

This is a repository of our open source React Native SDK. Huge shoutout to our friends at Dispatcher, Inc. for their help in compiling the initial version of this SDK. This SDK will help you handle iOS Universal Links, Android App Link, deferred deep links, do install attribution and much more!

v0.8.0 has just been released. If you currently override onStop in MainActivity.java be sure not to invoke RNBranchModule.onStop()

build status npm version npm downloads

Installation

  1. npm install --save react-native-branch
  2. rnpm link react-native-branch or link the project manually
  3. Add pod 'Branch' to your ios/Podfile (details)
  4. cd ios && pod install
  5. Follow the setup instructions

If you are new to react-native or cocoa-pods, read below for more details:

Next Steps

In order to get full branch support you will need to setup your ios and android projects accordingly:

Please see the branch SDK Integration Guide for complete setup instructions.

Additional Resources

Usage

import branch from 'react-native-branch'

// Subscribe to incoming links (both branch & non-branch)
branch.subscribe(({params, error, uri}) => {
  if (params) { /* handle branch link */ }
  else { /* handle uri */ }
})

let lastParams = await branch.getLatestReferringParams() // params from last open
let installParams = await branch.getFirstReferringParams() // params from original install
branch.setIdentity('theUserId')
branch.userCompletedAction('Purchased Item', {item: 123})
branch.logout()

let branchUniversalObject = branch.createBranchUniversalObject('canonicalIdentifier', {metadata: {prop1: 'test', prop2: 'abc'}, contentTitle: 'Cool Content!', contentDescription: 'Cool Content Description'}

let shareOptions = { messageHeader: 'Check this out', messageBody: 'No really, check this out!' }
let linkProperties = { feature: 'share', channel: 'RNApp' }
let controlParams = { $desktop_url: 'http://example.com/home', $ios_url: 'http://example.com/ios' }
let {channel, completed, error} = await branchUniversalObject.showShareSheet(shareOptions, linkProperties, controlParams)
let {url} = await branchUniversalObject.generateShortUrl(linkProperties, controlParams)
let viewResult = await branchUniversalObject.registerView()
let spotlightResult = await branchUniversalObject.listOnSpotlight()

let rewards = await branch.loadRewards()
let redeemResult = await branch.redeemRewards(amount, bucket)
let creditHistory = await branch.getCreditHistory()

Linking

listener (function)
Adds a change listener. Listener takes 1 argument with the shape { params, uri, error}. The listener will be called for all incoming links. Branch links will have params, plain deep links will only have a uri.

Returns a promise that resolves to the most recent referring params. Because params come in asynchronously, in most cases it is better to use the subscribe method to receive the params as soon as they are available.

Returns a promise to resolves with the first install referring params.

The params object is returned by various linking methods including subscribe, getLatestReferringParams, and getFirstReferringParams. Params will contain any data associated with the Branch link that was clicked before the app session began.

Branch returns explicit parameters every time. Here is a list, and a description of what each represents.

  • ~ denotes analytics
  • + denotes information added by Branch
Parameter Meaning
~channel The channel on which the link was shared, specified at link creation time
~feature The feature, such as invite or share, specified at link creation time
~tags Any tags, specified at link creation time
~campaign The campaign the link is associated with, specified at link creation time
~stage The stage, specified at link creation time
~creation_source Where the link was created ('API', 'Dashboard', 'SDK', 'iOS SDK', 'Android SDK', or 'Web SDK')
+match_guaranteed True or false as to whether the match was made with 100% accuracy
+referrer The referrer for the link click, if a link was clicked
+phone_number The phone number of the user, if the user texted himself/herself the app
+is_first_session Denotes whether this is the first session (install) or any other session (open)
+clicked_branch_link Denotes whether or not the user clicked a Branch link that triggered this session
+click_timestamp Epoch timestamp of when the click occurred

Any additional data attached to the branch link will be available unprefixed.

User Methods

Set an identifier for the current user.

Logout the current user.

Register a user action with branch.

Branch Universal Object

Create a branch universal object.
canonicalIdentifier the unique identifier for the content.
universalObjectOptions options for universal object as defined [below][#universalobjectoptions]. Returns an object with methods generateShortUrl, registerView, listOnSpotlight, and showShareSheet.

The following methods are available on the resulting branchUniversalObject:

shareOptions as defined below
linkProperties as defined below
controlParams as defined below
Returns an object with { channel, completed, error }

linkProperties as defined below
controlParams as defined below
Returns an object with { url }

Register a view for this universal object.

List the univeral object in spotlight (ios only).

An object of options for the branchUniversalObject.

Key TYPE DESCRIPTION
canonicalIdentifier String The object identifier
title String The object title
contentDescription String Object Description
contentImageUrl String The Image URL
contentIndexingMode String Indexing Mode 'private' or 'public'
metadata Object Custom key/value

An object of link properties.

KEY TYPE MEANING
feature string This is the feature of your app that the link might be associated with. eg: if you had built a referral program, you would label links with the feature referral
alias string Specify a link alias in place of the standard encoded short URL (e.g., [branchsubdomain]/youralias or yourdomain.co/youralias). Link aliases are unique, immutable objects that cannot be deleted. Aliases on the legacy bnc.lt domain are incompatible with Universal Links and Spotlight
channel string Use channel to tag the route that your link reaches users. For example, tag links with ‘Facebook’ or ‘LinkedIn’ to help track clicks and installs through those paths separately
stage string Use this to categorize the progress or category of a user when the link was generated. For example, if you had an invite system accessible on level 1, level 3 and 5, you could differentiate links generated at each level with this parameter
duration int duration of the link.

Control parameters for the link.

KEY TYPE MEANING
$fallback_url string Change the redirect endpoint for all platforms - so you don’t have to enable it by platform
$desktop_url string Change the redirect endpoint on desktops
$android_url string Change the redirect endpoint for Android
$ios_url string Change the redirect endpoint for iOS
$ipad_url string Change the redirect endpoint for iPads
$fire_url string Change the redirect endpoint for Amazon Fire OS
$blackberry_url string Change the redirect endpoint for Blackberry OS
$windows_phone_url string Change the redirect endpoint for Windows OS
KEY TYPE MEANING
messageHeader string The header text
messageBody string The body text
emailSubject string The subject of the email channel if selected

Referral Methods

Load rewards.

Redeem rewards. amount the amount to redeem
bucket (optional) the bucket to redeem from.

Get the credit history as an array.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Java 42.4%
  • Objective-C 32.5%
  • JavaScript 20.8%
  • Python 2.7%
  • Ruby 1.6%