Skip to content

The Cordova SDK for deferred deep linking is a thin wrapper around our native iOS/Android SDKs. Branch helps mobile apps grow with deep links / deeplinks that power referral systems, sharing links and invites with full attribution and analytics.

License

Notifications You must be signed in to change notification settings

pragunvohra/Cordova-Ionic-PhoneGap-Deferred-Deep-Linking-SDK

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Branch Metrics Cordova/Ionic/Phonegap SDK Reference

This is a repository of our open source Cordova | Phonegap | Ionic SDK, and the information presented here serves as a reference manual for the SDK. This SDK is a See the table of contents below for a complete list of the content featured in this document.

IMPORTANT: Upgrading to V 2.0

On 2/27, we revamped this module to be a thin wrapper around our native iOS/Android SDKs. This fixed a ton of bugs and added additional functionality, but will require you to change the interfaces. If you don't have time to do so, just use a reference to version 1.8, which we're storing in locked branch called 'v1.8.0-locked'.

Get the Demo App

There's a full demo app embedded in this repository. It should serve as an example integration and help guide you in resolving any bugs you encounter. If you think you've got a bug, please first check that it's present in the demo app before writing in. You can find the source here.

Additional Resources

Installation

The compiled iOS SDK footprint is 180kb The compiled Android SDK footprint is 187kb

Command link install

Install parameters:

  • BRANCH_KEY - Your Branch live API key. You can sign up for your own Branch key at https://dashboard.branch.io.
  • BRANCH_TEST_KEY - Your Branch test API key. You can sign up for your own Branch key at https://dashboard.branch.io.
  • URI_SCHEME - It could be your app name or the URI set in your Branch dashboard. As a reminder, the URI scheme is what you use to open your app from a browser, i.e. yourapp://.
  • [optional] ENCODED_ID - This is for supporting App Links (6.0+) on Android. You can obtain the encodied id from the Branch dashboard. For more info about App Links, please see this section of the Android readme.

Cordova

cordova plugin add https://github.com/BranchMetrics/Cordova-Ionic-PhoneGap-Deferred-Deep-Linking-SDK.git --variable BRANCH_KEY=<your-branch-key> --variable BRANCH_TEST_KEY=<your-branch-key> --variable URI_SCHEME=<your-app-uri-scheme-without-colon-and-slashes>

example:

cordova plugin add https://github.com/BranchMetrics/Cordova-Ionic-PhoneGap-Deferred-Deep-Linking-SDK.git --variable BRANCH_KEY=key_live_fnmRM1FXtu11t6e4LU8WsldpvDcA0bzv --variable BRANCH_TEST_KEY=key_test_oicIH5u2yxW9w3i6UZdfCiokyrixWpBJ --variable URI_SCHEME=branchsters

Phonegap

phonegap plugin add https://github.com/BranchMetrics/Cordova-Ionic-PhoneGap-Deferred-Deep-Linking-SDK.git --variable BRANCH_KEY=your-branch-key --variable BRANCH_TEST_KEY=your-branch-key --variable URI_SCHEME=your-app-uri-scheme --variable ENCODED_ID=your-encoded-id

example:

phonegap plugin add https://github.com/BranchMetrics/Cordova-Ionic-PhoneGap-Deferred-Deep-Linking-SDK.git --variable BRANCH_KEY=key_live_fnmRM1FXtu11t6e4LU8WsldpvDcA0bzv --variable BRANCH_TEST_KEY=key_test_oicIH5u2yxW9w3i6UZdfCiokyrixWpBJ --variable URI_SCHEME=branchsters

NPM

npm install branch-cordova-sdk --variable BRANCH_KEY=your-branch-key --variable BRANCH_TEST_KEY=your-branch-key --variable URI_SCHEME=your-app-uri-scheme

example:

npm install branch-cordova-sdk --variable BRANCH_KEY=key_live_fnmRM1FXtu11t6e4LU8WsldpvDcA0bzv --variable BRANCH_TEST_KEY=key_test_oicIH5u2yxW9w3i6UZdfCiokyrixWpBJ --variable URI_SCHEME=branchsters

Additional App Permissions

To be able to use some of the deep linking capabilities of the app, some manifest files are needed to be configured. Please note that you don't have to do anything anymore for setting up the Register a URI Scheme and add your Branch key as this was already done for you automatically on installing the plugin.

iOS: Enable Universal Links

In iOS 9.2, Apple dropped support for URI scheme redirects. You must enable Universal Links if you want Branch-generated links to work in your iOS app. To do this:

  1. enable Associated Domains capability on the Apple Developer portal when you create your app's bundle identifier.
  2. In your Dashboard Link Settings, tick the Enable Universal Links checkbox and provide the Bundle Identifier and Apple Team ID in the appropriate boxes. `

Add the following entry to your application's config.xml:

<branch-config>
    <ios-team-id value="your_ios_team_id" />
    <android-prefix value="/X9Ug" />
    <host name="bnc.lt" scheme="https" />
</branch-config>

You can get your iOS Team ID from the Apple Developer Portal. Once done, you have successfully enabled universal links for iOS.


Plugin Methods

Some methods are promisified, therefore you can easily get its success and error callback by chaining .then() method.

Example

Branch.getFirstReferringParams().then(function (res) {
  // Success Callback
  console.log(res);
}, function (err) {
  // Error Callback
  console.error(err);
});
  1. Branch Session
  1. Branch Universal Object
  1. Referral System Rewarding

setDebug(isEnable)

Setting the SDK debug flag will generate a new device ID each time the app is installed instead of possibly using the same device id. This is useful when testing.

Parameters

options: boolean - Boolean flag if debug mode should be enabled or not.

Usage
Branch.setDebug(true);

initSession()

Initializes the branch instance. Note: setDebug() should be called first before calling this method.

Usage

The initSession() method automatically also sets an internal deep link hander whose data can be accesed by implementing the required DeepLinkHandler() method. To implement, first call the method initSession:

onDeviceReady: function() {
    Branch.initSession();
},
onResume: function() {
    Branch.initSession();
},
initialize: function() {
    document.addEventListener('resume', onResume, false);
    document.addEventListener('deviceready', onDeviceReady, false);
},

Then add the method DeepLinkHandler() which will act as our callback when the session beings. The deep link data will be included here:

function DeepLinkHandler(data) {
    alert('Data from initSession: ' + data.data);
}

getFirstReferringParams()

Retrieves the install session parameters.

Usage
Branch.getFirstReferringParams().then(function (res) {
  // Success Callback
  console.log(res);
}).catch(function (err) {
  // Error Callback
  console.error(err);
});

getLatestReferringParams()

Retrieves the session (install or open) parameters.

Usage
Branch.getLatestReferringParams().then(function (res) {
  // Success Callback
  console.log(res);
}).catch(function (err) {
  // Error Callback
  console.error(err);
});

setIdentity(object)

Sets the identity of a user and returns the data. To use this function, pass a unique string that identifies the user - this could be an email address, UUID, Facebook ID, etc.

Parameters

identity: string - A string uniquely identifying the user, ofetn a user ID or email address.

Usage
Branch.setIdentity("new_identity").then(function (res) {
  // Success Callback
  console.log(res);
}).catch(function (err) {
  // Error Callback
  console.error(err);
});

logout()

Logs out the current session, replaces session IDs and identity IDs.

Usage
Branch.logout();

userCompletedAction(action[, metaData])

Registers custom events.

Parameters

action: string - A string for your custom action (e.g. "completed_purchase", "wrote_message", etc.)

metaData: object [Optional] - Custom values to be passed with the action

Usage
Branch.userCompletedAction('complete_purchase');

Branch.userCompletedAction('registered', { user: 'Test' });

Branch Universal Object

As more methods evolved in iOS, we've found that it was increasingly hard to manage them all. We abstracted as many as we could into the concept of a Branch Universal Object. This is the object that is associated with the thing you want to share (content or user). You can set all the metadata associated with the object and then call action methods on it to get a link or index in Spotlight.

createBranchUniversalObject(object)

Initializes the universal Branch object.

Parameters

options: object - Options in creating object.

object
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'
contentMetadata Object Custom key/value
Usage
var branchUniversalObj = null;

Branch.createBranchUniversalObject({
  canonicalIdentifier: 'identifier',
  title: 'Just another title',
  contentDescription: 'Just another description',
  contentImageUrl: '/img.jpg',
  contentIndexingMode: 'public'
}).then(function (newBranchUniversalObj) {
  // Success Callback
  branchUniversalObj = newBranchUniversalObj;
  console.log(newBranchUniversalObj);
}, function (err) {
  // Error Callback
  console.error(err);
});

registerView()

If you want to track how many times a user views a particular piece of content, you can call this method in viewDidLoad or viewDidAppear to tell Branch that this content was viewed.

Usage
branchUniversalObj.registerView();

generateShortUrl(options, controlParameters)

Once you've created your Branch Universal Object, which is the reference to the content you're interested in, you can then get a link back to it with the mechanism described below.

Parameters

options: object - Options needed to generate the URL.

KEY TYPE MEANING
feature string The feature of the link
alias string The alias of the link
channel string The channel of the link
stage string The stage of the link
duration int duration of the link.

controlParameters: object - Link properties needed to generate the URL.

KEY TYPE MEANING
$fallback_url string The fallback URL
$desktop_url string The URL for desktop
$android_url string The URL for Android
$ios_url string The URL for iPhone
$ipad_url string The URL for iPad
$fire_url string The URL for Kindle Fire
$blackberry_url string The URL for Blackberry
$windows_phone_url string The URL for Windows phone
Usage
branchUniversalObj.generateShortUrl({
  // put your link properties here
  "feature" : "sample-feature",
  "channel" : "sample-channel",
  "stage" : "sample-stage"
}, {
  // put your control parameters here
  "$desktop_url" : "http://desktop-url.com",
}).then(function (res) {
    // Success Callback
    console.log(res.generatedUrl);
}, function (err) {
    // Error Callback
    console.error(err);
});

showShareSheet(options, controlParameters)

UIActivityView is the standard way of allowing users to share content from your app. Once you've created your Branch Universal Object, which is the reference to the content you're interested in, you can then automatically share it without having to create a link using the mechanism below.

Sample Android Share Sheet

Android Share Sheet

Sample UIActivityView Share Sheet

UIActivityView Share Sheet

The Branch iOS SDK includes a wrapper on the UIActivityViewController, that will generate a Branch short URL and automatically tag it with the channel the user selects (Facebook, Twitter, etc.).

Parameters

options: object - Options needed to generate the URL.

KEY TYPE MEANING
feature string The feature of the link
alias string The alias of the link
channel string The channel of the link
stage string The stage of the link
duration int duration of the link.

controlParameters: object - Link properties needed to generate the URL.

KEY TYPE MEANING
$fallback_url string The fallback URL
$desktop_url string The URL for desktop
$android_url string The URL for Android
$ios_url string The URL for iPhone
$ipad_url string The URL for iPad
$fire_url string The URL for Kindle Fire
$blackberry_url string The URL for Blackberry
$windows_phone_url string The URL for Windows phone
Usage
branchUniversalObj.showShareSheet({
  // put your link properties here
  "feature" : "sample-feature",
  "channel" : "sample-channel",
  "stage" : "sample-stage",
  "duration" : 1,
}, {
  // put your control parameters here
  "$desktop_url" : "http://desktop-url.com",
});
Share Sheet Callbacks (Android ONLY)

To implement the callback, you must add listeners to the following events:

onShareSheetLaunched

The event fires when the share sheet is presented.

branchUniversalObj.onShareSheetLaunched(function () {
  console.log('Share sheet launched');
});
onShareSheetDismissed

The event fires when the share sheet is dismissed.

branchUniversalObj.onShareSheetDismissed(function () {
  console.log('Share sheet dimissed');
});
onLinkShareResponse

The event returns a dictionary of the response data.

branchUniversalObj.onLinkShareResponse(function (res) {
  console.log('Share link response: ' + JSON.stringify(res));
});
onChannelSelected

The event fires when a channel is selected.

branchUniversalObj.onChannelSelected(function (res) {
  console.log('Channel selected: ' + JSON.stringify(res));
});

Note: Callbacks in iOS are ignored. There is no need to implement them as the events are handled by UIActivityViewController.

Note: Avoid passing alias in iOS. Adding an alias key in the options parameter will return a Non-Universal link which will not work in iOS 9.2.

listOnSpotlight()

Note: iOS only. Used for Spotlight listing

Usage
branchUniversalObj.listOnSpotlight().then(function (res) {
  // Success Callback
  console.log(res);
}).catch(function (err) {
  // Error Callback
  console.error(err);
});

Referral System Rewarding

loadRewards()

Reward balances change randomly on the backend when certain actions are taken (defined by your rules), so you'll need to make an asynchronous call to retrieve the balance. Here is the syntax:

Usage
Branch.loadRewards().then(function (rewards) {
  // Success Callback
  console.log(rewards);
}).catch(function (err) {
  // Error Callback
  console.error(err);
});

redeemRewards(value)

Redeems a reward with the given amount/value.

Parameters

KEY TYPE MEANING
value int Amount to be redeemed.
bucket int Bucket where the amount will be redeemed. optional
Usage
Branch.redeemRewards(100, "default").then(function (res) {
  // Success Callback
  console.log(res);
}).catch(function (err) {
  // Error Callback
  console.error(err);
});

creditHistory()

This call will retrieve the entire history of credits and redemptions from the individual user. To use this call, implement like so:

Usage
Branch.creditHistory().then(function (history) {
  // Success Callback
  console.log(history);
}, function (err) {
  // Error Callback
  console.error(err);
});

The response will return an array that has been parsed from the following JSON:

## Bugs / Help / Support

Feel free to report any bugs you might encounter in the repo's issues. Any support inquiries outside of bugs
please send to [support@branch.io](mailto:support@branch.io).

About

The Cordova SDK for deferred deep linking is a thin wrapper around our native iOS/Android SDKs. Branch helps mobile apps grow with deep links / deeplinks that power referral systems, sharing links and invites with full attribution and analytics.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Objective-C 83.0%
  • JavaScript 9.8%
  • Java 6.2%
  • Other 1.0%