React Native Full Reference

GitHub

To see more information about these methods, visit the Branch React Native SDK GitHub repository.

createBranchUniversalObject

A BranchUniversalObject instance represents a unique piece of content, such as an article, video, or item for sale.

See our guide on best practices for creating Branch Universal Objects.

Example Usage

import branch from 'react-native-branch'

let buo = await branch.createBranchUniversalObject('content/12345', {
  title: 'My Content Title',
  contentDescription: 'My Content Description',
  contentMetadata: {
    customMetadata: {
      key1: 'value1'
    }
  }
})

generateShortUrl

Example Usage

import branch from 'react-native-branch'

let buo = await branch.createBranchUniversalObject('content/12345', {
  title: 'My Content Title',
  contentDescription: 'My Content Description',
  contentMetadata: {
    customMetadata: {
      key1: 'value1'
    }
  }
})

let linkProperties = {
  feature: 'sharing',
  channel: 'facebook',
  campaign: 'content 123 launch'  
}

let controlParams = {
  $desktop_url: 'https://example.com/home',
  custom: 'data'   
}

let {url} = await buo.generateShortUrl(linkProperties, controlParams)

getLatestReferringParams

Retrieve data from a Branch Deep Link.

This method is essentially a synchronous method that retrieves the latest referring link parameters stored by the native SDK. However, React Native does not support synchronous calls to native code from JavaScript, so the method returns a promise. You must await the response or use then to receive the result.

However, this is only a restriction of React Native. The purpose of getLatestReferringParams is to retrieve those parameters one time. The promise will only return one result. It will not continue to return results when links are opened or wait for a link to be opened. This method is not intended to notify the app when a link has been opened.

Best practice for this method is to receive the data from the listener (to prevent a race condition).

Returns Branch Deep Link properties.

Example Usage

import branch from 'react-native-branch'

// Listener
branch.subscribe({
    onOpenStart: ({
        uri,
        cachedInitialEvent
    }) => {
        console.log(
            'subscribe onOpenStart, will open ' +
            uri +
            ' cachedInitialEvent is ' +
            cachedInitialEvent,
        );
    },
    onOpenComplete: ({
        error,
        params,
        uri
    }) => {
        if (error) {
            console.error(
                'subscribe onOpenComplete, Error from opening uri: ' +
                uri +
                ' error: ' +
                error,
            );
            return;
        }
        else if (params) {
            if (!params['+clicked_branch_link']) {
                if (params['+non_branch_link']) {
                    console.log('non_branch_link: ' + uri);
                    // Route based on non-Branch links
                    return;
                }
            } else {
                // Handle params
                let deepLinkPath = params.$deeplink_path as string; 
                let canonicalUrl = params.$canonical_url as string;
                // Route based on Branch link data 
                return
            }
        }
    },
});

let latestParams = await branch.getLatestReferringParams() // Params from last open

getFirstReferringParams

Retrieve data from a Branch Deep Link.

This method is essentially a synchronous method that retrieves the latest referring link parameters stored by the native SDK. However, React Native does not support synchronous calls to native code from JavaScript, so the method returns a promise. You must await the response or use then to receive the result.

Best practice for this method is to receive the data from the listener (to prevent a race condition).

Returns Branch Deep Link properties.

Example Usage

import branch from 'react-native-branch'

// Listener
branch.subscribe({
    onOpenStart: ({
        uri,
        cachedInitialEvent
    }) => {
        console.log(
            'subscribe onOpenStart, will open ' +
            uri +
            ' cachedInitialEvent is ' +
            cachedInitialEvent,
        );
    },
    onOpenComplete: ({
        error,
        params,
        uri
    }) => {
        if (error) {
            console.error(
                'subscribe onOpenComplete, Error from opening uri: ' +
                uri +
                ' error: ' +
                error,
            );
            return;
        }
        else if (params) {
            if (!params['+clicked_branch_link']) {
                if (params['+non_branch_link']) {
                    console.log('non_branch_link: ' + uri);
                    // Route based on non-Branch links
                    return;
                }
            } else {
                // Handle params
                let deepLinkPath = params.$deeplink_path as string; 
                let canonicalUrl = params.$canonical_url as string;
                // Route based on Branch link data 
                return
            }
        }
    },
});

let installParams = await branch.getFirstReferringParams() // Params from original install

getBranchQRCode

Example Usage

import branch from 'react-native-branch'

var qrCodeSettings = {
    width: 500,
    codeColor: "#3b2016",
    backgroundColor: "#a8e689",
    centerLogo: "https://cdn.branch.io/branch-assets/159857dsads5682753-og_image.png",
    margin: 1,
    imageFormat: "PNG"
};

var buoOptions = {
    title: "A Test Title",
    contentDescription: "A test content desc",
    contentMetadata: {
        price: "200",
        productName: "QR Code Scanner",
        customMetadata: { "someKey": "someValue", "anotherKey": "anotherValue" }
    }
};

var lp = {
    feature: "qrCode",
    tags: ["test", "working"],
    channel: "facebook",
    campaign: "posters"
};

var controlParams = {
    $desktop_url: "https://www.desktop.com",
    $fallback_url: "https://www.fallback.com"
};

try {
    var result = await branch.getBranchQRCode(qrCodeSettings, buoOptions, lp, controlParams);
}
catch (err) {
    console.log('QR Code Err: ', err);
}

setIdentity

This method may be helpful if you have your own user IDs for customers, or you want referral and event data to persist across platforms or uninstall/reinstall. Using this method can make it easier to know when users access your service from different devices.

You can validate that an identity has been set using the Branch Dashboard.

Warning: Do not use this method to send PII to Branch.

Example Usage

import branch from 'react-native-branch'

branch.setIdentity('theUserId')
branch.logout()

logEvent

By default, the Branch React Native SDK tracks clicks, opens, installs, reinstalls and impressions automatically (out-of-the-box).

To log other Branch Events:

1. Create a BranchUniversalObject instance.

2. Create a BranchEventParams instance.

3. Use new BranchEvent to create a Branch Event with the newly created BranchUniversalObject and BranchEventParams instances

4. Use the logEvent() method.

Learn more about tracking events with the Branch React Native SDK in our Advanced Features guide.

Example Usage

import branch from 'react-native-branch'

let buo = await branch.createBranchUniversalObject(
  "item/12345",
  {
    canonicalUrl: "https://branch.io/item/12345",
    title: "My Item Title",
    contentMetadata: {
      quantity: 1,
      price: 23.20,
      sku: "1994320302",
      productName: "my_product_name1",
      productBrand: "my_prod_Brand1",
      customMetadata: {
            custom_key1: "custom_value1",
            custom_key2: "custom_value2"
    		}
  	}
  }
)

let params = {
  transaction_id: "tras_Id_1232343434",
  currency: "USD",
  revenue: 180.2,
  shipping: 10.5,
  tax: 13.5,
  coupon: "promo-1234",
  affiliation: "high_fi",
  description: "Preferred purchase",
  purchase_loc: "Palo Alto",
  store_pickup: "unavailable",
  customData: {
   "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
   "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
  }
}

let event = new BranchEvent(BranchEvent.Purchase, [buo], params)
event.logEvent()

openURL

Example Usage

import branch from 'react-native-branch'

branch.openURL("https://example.app.link/u3fzDwyyjF")

// Finish the Android current activity before opening the link
// Results in a new activity window
// Ignored on iOS
branch.openURL("https://example.app.link/u3fzDwyyjF", {newActivity: true})

subscribe

Example Usage

import branch from 'react-native-branch'

branch.subscribe({
    onOpenStart: ({
        uri,
        cachedInitialEvent
    }) => {
        console.log(
            'subscribe onOpenStart, will open ' +
            uri +
            ' cachedInitialEvent is ' +
            cachedInitialEvent,
        );
    },
    onOpenComplete: ({
        error,
        params,
        uri
    }) => {
        if (error) {
            console.error(
                'subscribe onOpenComplete, Error from opening uri: ' +
                uri +
                ' error: ' +
                error,
            );
            return;
        }
        else if (params) {
            if (!params['+clicked_branch_link']) {
                if (params['+non_branch_link']) {
                    console.log('non_branch_link: ' + uri);
                    // Route based on non-Branch links
                    return;
                }
            } else {
                // Handle params
                let deepLinkPath = params.$deeplink_path as string; 
                let canonicalUrl = params.$canonical_url as string;
                // Route based on Branch link data 
                return
            }
        }
    },
});

setRequestMetadata

Some third-party Data Integration Partners require setting certain identifiers before initializing Branch.

To do this:

1. Add deferInitForPluginRuntime to your branch.json file.

2. Use the setRequestMetadata() method to set your identifiers.

Example Usage

import branch from 'react-native-branch'

// Call `setRequestMetadata` before `subscribe`
branch.setRequestMetadata('$analytics_visitor_id', '000001')

branch.subscribe({ error, params } => {
  // ...
})

Learn more in our React Native Advanced Features guide.

openURL

Example Usage

import branch from 'react-native-branch'

let data = {
  "aps": {
    "alert": "Push notification with a Branch deep link",
    "badge": "1"
  },
  "branch": "https://example.app.link/u3fzDwyyjF"
}

branch.openURL(data["branch"],{newActivity: true})

disableTracking

Example Usage

import branch from 'react-native-branch'

branch.disableTracking(true)

isTrackingDisabled

Example Usage

import branch from 'react-native-branch'

branch.isTrackingDisabled()

logout

Example Usage

import branch from 'react-native-branch'

branch.logout()

addFacebookPartnerParameter

Example Usage

import branch from 'react-native-branch'

branch.addFacebookPartnerParameter("key","value")

addSnapPartnerParameter

Example Usage

import branch from 'react-native-branch'

branch.addSnapPartnerParameter("key","value")

clearPartnerParameters

Example Usage

import branch from 'react-native-branch'

branch.clearPartnerParameters("key","value")

handleATTAuthorizationStatus

Example Usage

import branch from 'react-native-branch'

// Retrieve ATT authorization status
// ...

// Pass ATT authorization status to Branch
let ATTAuthorizationStatus = "restricted"
branch.handleATTAuthorizationStatus(ATTAuthorizationStatus)

lastAttributedTouchData

Example Usage

import branch from 'react-native-branch'

const attributionWindow = 365;

// `latData` is an object
branch.lastAttributedTouchData(attributionWindow, (latData) => {
// ...
});

setPreInstallCampaign

Example Usage

import branch from 'react-native-branch'

branch.setPreinstallCampaign("My Pre-Install Campaign")

setPreInstallPartner

Example Usage

import branch from 'react-native-branch'

branch.setPreInstallPartner("My Pre-Install Partner")

setDMAParamsForEEA

Warning: Omitted by Default

Please note that the 3 consent parameters related to setDMAParamsForEEA are all omitted by default.

Failure to include user consent signals may result in attribution or campaign performance degradation. For additional information, please reach out to your Google AM.

Making a successful setDMAParamsForEEA() call requires that all 3 parameters be set.

Example Usage

import branch from 'react-native-branch'

// Example for an EEA resident who has denied both ad personalization and data usage consent
branch.setDMAParamsForEEA(true,false,false)

// Example for an EEA resident who has consented to ad personalization but denied data usage consent
branch.setDMAParamsForEEA(true,true,false)

// Example for an EEA resident who has denied ad personalization but granted data usage consent
branch.setDMAParamsForEEA(true,false,true)