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.
Objective-C JavaScript Java HTML CSS Shell C
Latest commit b1d8a0e Jan 17, 2017 @ethanneff ethanneff committed on GitHub docs: update singleInstance to singleTask
Permalink
Failed to load latest commit information.
hooks.es6 chore: added comments to beforepluginhook Dec 9, 2016
hooks chore: added comments to beforepluginhook Dec 9, 2016
src fix: userCompletedAction works with no metadata Jan 9, 2017
testbed style: custom event now outputs blanks Jan 9, 2017
tests-harness style: run `gulp jscs-fix` against entire codebase Aug 10, 2016
tests.es6 chore(babel): move js sources into es6 folders Aug 10, 2016
tests fix: updated iOS SDK to 0.12.16 [ √ iOS ] Nov 15, 2016
www.es6 fix: handled crash for empty userCompletedAction Jan 9, 2017
www fix: handled crash for empty userCompletedAction Jan 9, 2017
.eslintrc chore(lint): remove File and mixpanel from eslintrc globals Aug 8, 2016
.gitattributes chore: add .gitattributes Oct 4, 2016
.gitignore chore: removed the t1 testbed from the gitignore Nov 16, 2016
.jscsrc chore(lint): implement linting in gulpfile Aug 8, 2016
.npmignore chore: npm publish should now include build output Aug 10, 2016
.travis.yml chore: testing whats wrong with travis Aug 10, 2016
CHANGELOG.md chore: updated changelog, updated version, and ran prerelease Nov 15, 2016
CONTRIBUTING.md fix: spelling correction Sep 29, 2016
DEVELOPING.md docs: added new way to build testbed Jan 9, 2017
ISSUE_TEMPLATE fix: updated how to contact us Nov 15, 2016
LICENSE deleting old stuff Feb 25, 2016
README.md docs: update singleInstance to singleTask Jan 18, 2017
build-branch-extras.gradle remove exclusion Sep 10, 2016
gulpfile.js Merge pull request #241 from BranchMetrics/eneff-fix-testing Nov 17, 2016
package.json chore: removed end line tabs Dec 9, 2016
plugin.template.xml fix: relocated initial comment for VS TACO Dec 27, 2016
plugin.xml chore: updated iOS 0.12.23 Jan 9, 2017

README.md

Branch for Cordova/PhoneGap/Ionic

Travis npm downloads npm version npm version

Hyperlinks can navigate to a website, but not to your app.

Branch deep links allow users to install, open, and navigate to content inside your app.

Branch deep links will grow your app.

Convert web users to app users, enable user-to-user sharing, personalize user experiences, track users, track referrals, track campaigns, track conversions, and increase overall engagement.

Branch for Cordova, PhoneGap, and Ionic

Questions? Contact us

Getting Started

  • Configure Branch

  • Install Branch

    • Cordova and PhoneGap and Ionic

      # terminal
      cordova plugin add branch-cordova-sdk --variable BRANCH_KEY=key_live_hiuejxqEdbHR8Tc1L92nmiijrse9OBpq --variable URI_SCHEME=branchcordova;
    • Change key_live_hiuejxqEdbHR8Tc1L92nmiijrse9OBpq and branchcordova to the values in your Branch Dashboard

  • Configure App

    • Cordova and Ionic

      <!-- sample config.xml -->
      <widget id="com.eneff.branch.cordova" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
        <branch-config>
          <ios-team-id value="PW4Q8885U7"/>
          <host name="2d0s.app.link" scheme="https" />
          <host name="2d0s-alternate.app.link" scheme="https" />
        </branch-config>
        <preference name="AndroidLaunchMode" value="singleTask" />
    • PhoneGap

      <!-- sample config.xml -->
      <widget id="com.eneff.branch.cordova" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:gap="http://phonegap.com/ns/1.0">
        <branch-config>
          <ios-team-id value="PW4Q8885U7"/>
          <host name="2d0s.app.link" scheme="https" />
          <host name="2d0s-alternate.app.link" scheme="https" />
        </branch-config>
        <preference name="AndroidLaunchMode" value="singleTask" />
    • Change com.eneff.branch.cordova, PW4Q8885U7, 2d0s.app.link, and 2d0s-alternate.app.link to the values in your Branch Dashboard

  • Initialize Branch

    • Cordova and PhoneGap

      // sample index.js
      var app = {
        initialize: function() {
          this.bindEvents();
        },
        bindEvents: function() {
          document.addEventListener('deviceready', this.onDeviceReady, false);
          document.addEventListener('resume', this.onDeviceReady, false);
        },
        onDeviceReady: function() {
          app.branchInit();
        },
        onDeviceResume: function() {
          app.branchInit();
        },
        branchInit: function() {
          // Branch initialization
          Branch.initSession(function(data) {
            // read deep link data on click
            alert('Deep Link Data: ' + JSON.stringify(data));
          });
        }
      };
      
      app.initialize();
    • Ionic 1

      // sample app.js
      angular.module('starter', ['ionic', 'starter.controllers', 'starter.services'])
      
      .run(function($ionicPlatform) {
        $ionicPlatform.ready(function() {
          if (window.cordova && window.cordova.plugins && window.cordova.plugins.Keyboard) {
            cordova.plugins.Keyboard.hideKeyboardAccessoryBar(true);
            cordova.plugins.Keyboard.disableScroll(true);
          }
          if (window.StatusBar) {
            StatusBar.styleDefault();
          }
      
          // Branch initialization
          Branch.initSession(function(data) {
            // read deep link data on click
            alert('Deep Link Data: ' + JSON.stringify(data));
          });
        });
      })
      // ...
    • Ionic 2

      // sample app.component.js
      import { Component } from '@angular/core';
      import { Platform } from 'ionic-angular';
      import { StatusBar, Splashscreen } from 'ionic-native';
      import { TabsPage } from '../pages/tabs/tabs';
      
      // Branch import
      declare var Branch;
      
      @Component({
        template: `<ion-nav [root]="rootPage"></ion-nav>`
      })
      export class MyApp {
        rootPage = TabsPage;
      
        constructor(platform: Platform) {
          platform.ready().then(() => {
            StatusBar.styleDefault();
            Splashscreen.hide();
      
            // Branch initialization
            Branch.initSession(function(data) {
              // read deep link data on click
              alert('Deep Link Data: ' + JSON.stringify(data));
            });
          });
        }
      }
  • Test Deep Link iOS

    • Wait 15 minutes after saving changes on the Branch Dashboard

    • Create a deep link from the Branch Marketing Dashboard

    • Delete your app from the device (resets the Apple AASA scraping)

    • Compile your app (cordova build ios phonegap build ios ionic build ios)

    • Open the app in Xcode and set your Provisioning Profile Development Team

    • Launch your app to device (not Simulator or TestFlight)

    • Paste deep link in Apple Notes

    • Long press on the deep link (not 3D Touch)

    • Click Open in "APP_NAME" to open app (example)

  • Test Deep Link Android

    • Wait 15 minutes after saving changes on the Branch Dashboard

    • Create a deep link from the Branch Marketing Dashboard

    • Delete your app from the device

    • Compile your app (cordova build android phonegap build android ionic build android)

    • Launch your app to device (not Simulator or Genymotion)

    • Paste deep link in Google Hangouts

    • Tap on the deep link to open app

Features

  • Initialize Branch Features

    • Loads Branch into your app

    • Must be called on deviceready and resume

      // for development and debugging only
      Branch.setDebug(true)
      
      // sync with Mixpanel if installed
      Branch.setMixpanelToken('your_mixpanel_token')
      
      // Branch initialization
      Branch.initSession(function(data) {
        // read deep link data on click
        alert('Deep Link Data: ' + JSON.stringify(data))
      }).then(function(res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function(err) {
        alert('Error: ' + JSON.stringify(err))
      })
  • Create Content Reference

    • The Branch Universal Object encapsulates the thing you want to share (content or user)

    • Link Data: Universal Object Properties

      // only canonicalIdentifier is required
      var properties = {
        canonicalIdentifier: 'content/123',
        canonicalUrl: 'https://example.com/content/123',
        title: 'Content 123 Title',
        contentDescription: 'Content 123 Description ' + Date.now(),
        contentImageUrl: 'http://lorempixel.com/400/400/',
        price: 12.12,
        currency: 'GBD',
        contentIndexingMode: 'private',
        contentMetadata: {
          custom: 'data',
          testing: 123,
          this_is: true
        }
      }
      
      // create a branchUniversalObj variable to reference with other Branch methods
      var branchUniversalObj = null
      Branch.createBranchUniversalObject(properties).then(function (res) {
        branchUniversalObj = res
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
  • Create Deep Link

    • Creates a deep link URL with encapsulated data

    • Needs a Branch Universal Object

    • Link Data: Deep Link Properties

      // optional fields
      var analytics = {
        channel: 'facebook',
        feature: 'onboarding',
        campaign: 'content 123 launch',
        stage: 'new user',
        tags: ['one', 'two', 'three']
      }
      
      // optional fields
      var properties = {
        $desktop_url: 'http://www.example.com/desktop',
        $android_url: 'http://www.example.com/android',
        $ios_url: 'http://www.example.com/ios',
        $ipad_url: 'http://www.example.com/ipad',
        $deeplink_path: 'content/123',
        $match_duration: 2000,
        more_custom: 'data',
        even_more_custom: true,
        this_is_custom: 41231,
        this_is_date: Date.now()
      }
      
      branchUniversalObj.generateShortUrl(analytics, properties).then(function (res) {
        alert('Response: ' + JSON.stringify(res.url))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
  • Share Deep Link

    • Will generate a Branch deep link and tag it with the channel the user selects

    • Needs a Branch Universal Object

    • Link Data: Deep Link Properties

      // optional fields
      var analytics = {
        channel: 'facebook',
        feature: 'onboarding',
        campaign: 'content 123 launch',
        stage: 'new user',
        tags: ['one', 'two', 'three']
      }
      
      // optional fields
      var properties = {
        $desktop_url: 'http://www.example.com/desktop',
        more_custom: 'data',
        even_more_custom: true,
        this_is_custom: 41231
      }
      
      var message = 'Check out this link'
      
      // optional listeners (must be called before showShareSheet)
      branchUniversalObj.onShareSheetLaunched(function (res) {
        // android only
        console.log(res)
      })
      branchUniversalObj.onShareSheetDismissed(function (res) {
        console.log(res)
      })
      branchUniversalObj.onLinkShareResponse(function (res) {
        console.log(res)
      })
      branchUniversalObj.onChannelSelected(function (res) {
        // android only
        console.log(res)
      })
      
      // share sheet
      branchUniversalObj.showShareSheet(analytics, properties, message)
  • Read Deep Link

    • Retrieve Branch data from a deep link

    • Best practice to receive data from the listener

    • Listener

      // Branch initialization within your deviceready and resume
      Branch.initSession(function(deepLinkData) {
        // handler for deep link data on click
        alert('Response: ' + JSON.stringify(deepLinkData))
      })
    • First data

      Branch.getFirstReferringParams().then(function(res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function(err) {
        alert('Error: ' + JSON.stringify(err))
      })
    • Latest data

      Branch.getLatestReferringParams().then(function(res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function(err) {
        alert('Error: ' + JSON.stringify(err))
      })
  • Display Content

    • List content on iOS Spotlight

    • Needs a Branch Universal Object

      branchUniversalObj.listOnSpotlight().then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
  • Track Content

    • Track how many times a user views a particular piece of content

    • Needs a Branch Universal Object

      branchUniversalObj.registerView().then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
  • Track User

    • Sets the identity of a user (email, ID, UUID, etc) for events, deep links, and referrals

    • Must be a string

      var userId = '123456'
      Branch.setIdentity(userId).then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
      Branch.logout().then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
  • Track Event

    • Registers custom events

    • Must Track User before Track Event to associate events with a user

    • Event names open, install, and close are restricted by Branch

      var eventName = 'clicked_on_this'
      var metadata = { 'custom_dictionary': 123, 'anything': 'everything' }
      Branch.userCompletedAction(eventName, metaData).then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
      var eventName = 'clicked_on_this'
      Branch.userCompletedAction(eventName).then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
  • Handle Referrals

    • Referral points are obtained from events triggered by users from rules created on the Branch Dashboard

    • Get credits

    • Spend credits

      var amount = 10
      var bucket = 'this_bucket'
      Branch.redeemRewards(amount, bucket).then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
      var amount = 10
      Branch.redeemRewards(amount).then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
    • Load credits

      var bucket = 'this_bucket'
      Branch.loadRewards(bucket).then(function(res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function(err) {
        alert('Error: ' + JSON.stringify(err))
      })
      Branch.loadRewards().then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })
    • Load history

      Branch.creditHistory().then(function (res) {
        alert('Response: ' + JSON.stringify(res))
      }).catch(function (err) {
        alert('Error: ' + JSON.stringify(err))
      })

Troubleshooting

  • Testing: Key Points

    • Use the Branch key_live

    • Always use the Branch.initSession(function(data) {}) to read Deep Link data

    • Always test on device (simulator browser genymotion will break)

    • You must launch the app through Xcode for iOS

    • Other deep link plugins (ex cordova-universal-links-plugin) will interferer with Branch

  • Testing: Sample Testing App

  • Testing: Sample Integration App

    • Ionic 1

      • Install
      npm install -g cordova ionic;
      ionic start t3 tabs;
      cd t3;
      ionic platform add ios;
      ionic platform add android;
      ionic plugin remove io.branch.sdk;
      # values should be from your Branch Dashboard https://dashboard.branch.io/settings/link
      ionic plugin add https://github.com/BranchMetrics/Cordova-Ionic-PhoneGap-Deferred-Deep-Linking-SDK.git --variable BRANCH_KEY=key_live_jnBhaHwt5K8xtn4g4hblHoleqsocI6C2 --variable URI_SCHEME=branchionic;
      • Update config.xml
      <!-- values should be from your Branch Dashboard https://dashboard.branch.io/settings/link -->
      <widget id="com.eneff.branch.ionic" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
        <branch-config>
          <ios-team-id value="PW4Q8885U7"/>
          <host name="cluv.app.link" scheme="https"/>
          <host name="cluv-alternate.app.link" scheme="https"/>
        </branch-config>
      • update app.js
      // global function
      function DeepLinkHandler(data) {
        if (data) {
          alert('Data Link handler response: ' + JSON.stringify(data));
        }
      }
      
      angular.module('starter', ['ionic', 'starter.controllers', 'starter.services'])
      
      .run(function($ionicPlatform) {
        $ionicPlatform.ready(function() {
          if (window.cordova && window.cordova.plugins && window.cordova.plugins.Keyboard) {
            cordova.plugins.Keyboard.hideKeyboardAccessoryBar(true);
            cordova.plugins.Keyboard.disableScroll(true);
          }
          if (window.StatusBar) {
            StatusBar.styleDefault();
          }
      
          // Branch
          $ionicPlatform.on('deviceready', function(){
            Branch.setDebug(true);
            Branch.initSession();
          });
        });
      })
      
      // ...
      • Delete app off device

      • Compile ionic

      ionic build ios;
      • Run on device through xcode
      open -a Xcode platforms/ios/t3.xcodeproj;
  • Testing: Show Console Logs

    • iOS Simulator

      • cordova run ios;

      • Safari -> Preferences -> Advance -> Show Develop menu in menu bar

      • Safari -> Develop -> Simulator -> index.html -> Console

      • May need to unplug and replug device

      • May need to open Xcode and update provisioning profile

    • iOS Xcode

      • cordova plugin add cordova-plugin-console;

      • cordova build ios;

      • Xcode -> APP_LOCATION/platforms/ios/APP_NAME.Xcodeproj

      • Xcode -> App -> General -> Signing -> Team

      • Xcode -> Product -> Run

      • Xcode -> View -> Debug Area -> Activate Console

    • Android Device

      • Plug device in

      • cordova run android;

      • Chrome -> chrome://inspect/#devices -> Console

    • Android Genymotion

      • Genymotion -> Start

      • cordova run android;

      • Chrome -> chrome://inspect/#devices -> Console

  • Testing: Supported Platforms

    • Apps which support Branch deep links

      iOS Details Android Details
      Facebook NewsFeed Works when DeepViews are enabled
      Facebook Messanger Works when DeepViews are enabled Works except the app.link domain is not click-able
      Twitter
      Pinterest Works when DeepViews are enabled 🅾️
      Slack
      Chrome address bar 🅾️ 🅾️
      Chrome web page
      FireFox address bar 🅾️
      FireFox web page
      Safari address bar 🅾️
      Safari web page
      WeChat 🅾️ 🅾️
      WhatsApp
      Hangouts
      iMessage
      Apple Mail
      Gmail
  • Testing: Simulating an Install

    • Add Branch.setDebug(true); before Branch.initSession();

    • Delete app

    • [iOS only] iPhone -> Settings -> Privacy -> Advertising -> Reset Advertising Identifier -> Reset Identifier

    • Click on deep link (will navigate to fallback url because app is not installed)

    • Install the app

    • Open the app

    • Read from Branch.initSession(data) for +is_first_session = true

  • Link Domain: Custom

    • Cordova and PhoneGap and Ionic

      <!-- sample config.xml -->
      <branch-config>
        <ios-team-id value="PW4Q8885U7"/>
        <host name="custom.domain.com" scheme="https" />
      </branch-config>
    • Change PW4Q8885U7 and custom.domain.com to the values in your Branch Dashboard

  • Link Domain: Bnc.lt

    • Cordova and PhoneGap and Ionic

      <!-- sample config.xml -->
      <branch-config>
        <ios-team-id value="PW4Q8885U7"/>
        <android-prefix value="/WSuf" />
        <host name="bnc.lt" scheme="https" />
      </branch-config>
    • Change PW4Q8885U7 and /WSuf to the values in your Branch Dashboard

  • Link Data: Universal Object Properties

    • For Create Content Reference

    • Properties

      Key Default Usage Link Property
      canonicalIdentifier (Required) This is the unique identifier for content that will help Branch dedupe across many instances of the same thing. Suitable options: a website with pathing, or a database with identifiers for entities $canonical_identifier
      canonicalUrl The canonical URL, used for SEO purposes $canonical_url
      title The name for the piece of content $og_title
      contentDescription A description for the content $og_description
      contentImageUrl The image URL for the content $og_image_url
      price The price of the item $amount
      currency The currency representing the price in ISO 4217 currency code $currency
      contentIndexingMode "public" Can be set to either "public" or "private". Public indicates that you’d like this content to be discovered by other apps. $publicly_indexable
      contentMetadata Any custom key-value data e.g. { "custom": "data" }
  • Link Data: Deep Link Properties

    • For Create Deep Link and Share Deep Link

    • Analytics

      Key Default Usage
      channel 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
      feature This is the feature of your app that the link might be associated with. For example, if you had built a referral program, you would label links with the feature ‘referral’
      campaign Use this field to organize the links by actual campaign. For example, if you launched a new feature or product and want to run a campaign around that
      stage 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
      tags This is a free form entry with unlimited values ["string"]. Use it to organize your link data with labels that don’t fit within the bounds of the above
      alias Specify a link alias in place of the standard encoded short URL e.g. yourdomain.com/youralias. Link aliases are unique, immutable objects that cannot be deleted. You cannot change the alias of existing links. Aliases on the legacy bnc.lt domain are incompatible with Universal Links and Spotlight
      type 0 Set to 1 to limit deep linking behavior of the generated link to a single use. Set type to 2 to make link show up under Marketing Dashboard
    • Properties

      • Custom Data

        Key Value Usage
        random 123 Any key-value pair
        hello "world" Any key-value pair
        custom_data true Any key-value pair
      • Redirection

        Key Default Usage
        $fallback_url Change the redirect endpoint for all platforms - so you don’t have to enable it by platform. Note that Branch will forward all robots to this URL, which overrides any OG tags entered in the link. System-wide Default URL (set in Link Settings)
        $desktop_url Change the redirect endpoint on desktops Text-Me-The-App page (set in Link Settings)
        $ios_url Change the redirect endpoint for iOS App Store page for your app (set in Link Settings)
        $ipad_url Change the redirect endpoint for iPads $ios_url value
        $android_url Change the redirect endpoint for Android Play Store page for your app (set in Link Settings)
        $windows_phone_url Change the redirect endpoint for Windows OS Windows Phone default URL (set in Link Settings)
        $blackberry_url Change the redirect endpoint for Blackberry OS BlackBerry default URL (set in Link Settings)
        $fire_url Change the redirect endpoint for Amazon Fire OS Fire default URL (set in Link Settings)
        $ios_wechat_url Change the redirect endpoint for WeChat on iOS devices $ios_url value
        $android_wechat_url Change the redirect endpoint for WeChat on Android devices $android_url value
        $after_click_url URL redirect to after the main click redirect has completed
        $web_only false Force to open the $fallback_url instead of the app
      • Deep Link

        Key Default Usage
        $deeplink_path open?link_click_id=1234 Set the deep link path for all platforms - so you don’t have to enable it by platform. When the Branch SDK receives a link with this parameter set, it will automatically load the custom URI path contained within
        $android_deeplink_path Set the deep link path for Android apps When the Branch SDK receives a link with this parameter set, it will automatically load the custom URI path contained within
        $ios_deeplink_path Set the deep link path for iOS apps. When the Branch SDK receives a link with this parameter set, it will automatically load the custom URI path contained within
        $match_duration 7200 Lets you control the fingerprinting match timeout (the time that a click will wait for an app open to match) also known as attribution window. Specified in seconds
        $always_deeplink true Set to false to make links always fall back to your mobile site. Does not apply to Universal Links or Android App Links.
        $ios_redirect_timeout 750 Control the timeout that the client-side JS waits after trying to open up the app before redirecting to the App Store. Specified in milliseconds
        $android_redirect_timeout 750 Control the timeout that the clientside JS waits after trying to open up the app before redirecting to the Play Store. Specified in milliseconds
        $one_time_use false Set to true to limit deep linking behavior of the generated link to a single use. Can also be set using type
        $custom_sms_text Text for SMS link sent for desktop clicks to this link. Must contain {{ link }} Value of Text me the app page in Settings
      • Content

        Key Default Usage
        $publicly_indexable 1 Cannot modify here. Needs to be set by the Branch Universal Object
        $keywords Keywords for which this content should be discovered by. Just assign an array of strings with the keywords you’d like to use
        $canonical_identifier This is the unique identifier for content that will help Branch dedupe across many instances of the same thing. Suitable options: a website with pathing, or a database with identifiers for entities
        $exp_date 0 Cannot modify here. Needs to be set by the Branch Universal Object. Must be epoch timestamp with milliseconds
        $content_type This is a label for the type of content present. Apple recommends that you use uniform type identifier as described here
      • DeepView

        Key Default Usage
        $ios_deepview default_template The name of the deepview template to use for iOS
        $android_deepview default_template The name of the deepview template to use for Android
        $desktop_deepview default_template The name of the deepview template to use for the Desktop
      • Open Graph

        Key Default Usage
        $og_title Set the title of the link as it will be seen in social media displays
        $og_description Set the description of the link as it will be seen in social media displays
        $og_image_url Set the image of the link as it will be seen in social media displays
        $og_image_width Set the image’s width in pixels for social media displays
        $og_image_height Set the image’s height in pixels for social media displays
        $og_video Set a video as it will be seen in social media displays
        $og_url Set the base URL of the link as it will be seen in social media displays
        $og_type Set the type of custom card format link as it will be seen in social media displays
        $og_redirect (Advanced, not recommended) Set a custom URL that we redirect the social media robots to in order to retrieve all the appropriate tags
        $og_app_id (Rarely used) Sets the app id tag
      • Twitter

        Key Default Usage
        $twitter_card Set the Twitter card type of the link
        $twitter_title Set the title of the Twitter card
        $twitter_description Set the description of the Twitter card
        $twitter_image_url Set the image URL for the Twitter card
        $twitter_site Set the site for Twitter
        $twitter_app_country Set the app country for the app card
        $twitter_player Set the video player’s URL. Defaults to the value of $og_video.
        $twitter_player_width Set the player’s width in pixels
        $twitter_player_height Set the player’s height in pixels
  • Link Data: Convert to Ionic/Angular

    • Convert Branch deep link data from DeepLinkHandler into Ionic and Angular

    • Listen to Branch data, and save it into an Angular DeepLink

      // must be a global function
      function DeepLinkHandler(data) {
        if (data) {
          // access the angular Factory('DeepLink')
          angular.element(document.querySelector('[ng-app]')).injector().get('DeepLink').set(data);
          console.log('Data Link handler response: ' + JSON.stringify(data));
        }
      }
    • Create a DeepLink factory

      angular.module('starter.services', [])
      .factory('DeepLink', function($window, $timeout) {
        var data = {};
      
        return {
          get: function() {
            return data;
          },
          set: function(json) {
            // use the angular version of timeout
            $timeout(function() {
              // set the data
              data = json;
              // navigate example
              $window.location = '#/tab/chats/3';
            }, 0);
          }
        };
      });
    • Access DeepLink factory

      angular.module('starter.controllers', [])
      
      .controller('DashCtrl', function($scope, DeepLink) {
        $scope.content = {}
        $scope.buttonPressed = function() {
          // put branch data into a label that has ng-model content.data
          $scope.content.data = JSON.stringify(DeepLink.get());
        };
      })
  • Link Data: Global Listener Warning

    • After Branch SDK 2.4.0, deep link data is handled within Branch.initSession(DeepLinkDataFunction);

      • Listener [depreciated in 2.4.0]

        <!-- sample index.html -->
            <script>
              // required
              function DeepLinkHandler(data) {
                if (data) {
                  alert('Data Link Data Response: ' + JSON.stringify(data));
                }
              }
        
              // optional
              function NonBranchLinkHandler(data) {
                if (data) {
                  alert('Non-Branch Link Detected: ' + JSON.stringify(data));
                }
              }
            </script>
          </body>
        </html>
    • Use Branch.disableGlobalListenersWarnings(); to turn off the warning errors generated from DeepLinkHandler and NonBranchLinkHandler

  • Compiling: Incompatible Plugins

  • Compiling: Updating the Branch SDK

    # update cordova
    npm install -g cordova;
    
    # remove old Branch SDK cache
    cordova platform remove ios;
    cordova platform remove android;
    cordova platform remove browser;
    
    # add platforms back
    cordova platform add ios;
    cordova platform add android;
    
    # update Branch SDK
    cordova plugin remove io.branch.sdk;
    cordova plugin add branch-cordova-sdk --variable BRANCH_KEY=xxxx --variable URI_SCHEME=xxxx;
    
    # compile platform code
    cordova build ios;
    cordova build android;
    • Change xxxx, and xxxx to the values in your Branch Dashboard

    • cordova plugin add branch-cordova-sdk can sometimes miss installing dependencies if you run more than 1 command at a time

  • Compiling: Cordova Dependencies

    • Node

      /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)";
      brew update;
      brew install node;
    • Xcode

      • Install Xcode

      • Open Xcode -> agree to SDK license agreement

      • Open Xcode -> Create new Xcode project -> Run simulator -> Agree to developer mode on mac

    • Android Studio

      • Read instructions

      • Install JVM

      • Install Android Studio

      • Open Android Studio -> configure -> appearance/system settings/android sdk -> android 6.0 -> Okay

      • Open Android Studio -> New project -> ... -> Run -> Create new emulator -> Nexus 6p 23 -> Finish

        # add to ~/.bash_profile
        export ANDROID_HOME=$HOME/Library/Android/sdk
        export PATH=$ANDROID_HOME/tools:$PATH
        export PATH=$ANDROID_HOME/platform-tools:$PATH
        source ~/.bash_profile;
        android update sdk;
      • Install Android SDK build-tools 24.0.1

    • Genymotion [optional]

      • Install Virtual Box

      • Install Genymotion

      • Genymotion -> Add virtual device -> Google Nexus 6P - 6.0.0 - API 23 -> Next

  • Compiling: Visual Studio TACO

    • Download the latest source code and import the Branch SDK locally
  • Compiling: Multiple support-lib v4s

    • Branch does not depend on the android-support-v4 file, but other Cordova plugins could cause an issue

    • Add multiDexEnabled true inside defaultConfig tag in build.gradle

      defaultConfig {
        multiDexEnabled true
      }
    • Remove the android-support-v4.jar in Android libs directory

    • Run ./gradlew clean in the Android directory

    • Run android-support-v4 file for compiling

      compile ("com.google.android.gms:play-services-ads:9.+") {
        exclude module: "support-v4"
      }
  • Compiling: Missing Android Dependency

    • Gradle build cannot find io.branch.sdk.android:library:2.+ dependency

    • Add into your build.gradle file

      compile "io.branch.sdk.android:library:2.+"

Additional