README

This is just a simple HTTP client for the Branch Metrics API (Branch.io). At the moment it supports creating, updating and configuring Branch links. A future version will include retrieving data from existing links.

Table of Contents

• Important Notice
• Installation
• Basic usage
  • Get link data
  • Create new link
• Advanced Usage
  • Configure link instance
  • Analytical Data
  • Configure Link type
  • Configure custom data
  • Create link
  • Update link
• Usage with Laravel
• License

Important Notice

The latest versions after 1.1.x are not backwards compatible with the old versions 1.0.x.

Be careful when updating! If you want to upgrade to versions 1.1.x, please first follow the documentation to make the needed changes in your code

Installation

The package can be installed with Composer. Just run this command:

$ composer require iivannov/branchio

Basic usage

Get link data

$client = new \Iivannov\Branchio\Client(KEY, SECRET);
$link = $client->getLink($url);

Create new link

$link = new \Iivannov\Branchio\Link();
 
$link->setChannel('foo')
    ->setAlias('foobar123')
    ->setData([
        '$always_deeplink' => 'true',
        '$deeplink_path' => 'go-to-user-123'
        'user_id' => 123
    ]);
    
$client = new \Iivannov\Branchio\Client(KEY, SECRET);
$client->createLink($link);

Advanced Usage

Configure link instance

Link instance contains all the configurable options for a Branch Metrics link and provides method to set them.

$link = new \Iivannov\Branchio\Link();
 
// Set parameters separately
$link->setChannel('Channel name');
$link->setAlias('foobar123);
$link->setTags(['foo', 'bar']);

 
// It's possible to chain the set methods
$link->setChannel('Channel name')
    ->setAlias('foobar123')
    ->setTags(['foo', 'bar']);
    

Analytical Data

For full reference about the analytical options available please see: https://docs.branch.io/pages/links/integrate/#analytical-labels

$link->setChannel('Channel name');
 
$link->setFeature('Feature name');
 
$link->setCampaign('Campaign name');
 
$link->setStage('Stage name');
 
$link->setTags(['foo', 'bar']);
 
$link->setAlias('foobar123);
 
$link->setType(UrlType::ONCE);    

Configure Link type

You can easily set the deep linking behaviour by passing the type parameter. You have the following options:

UrlType::DEFAULT_TYPE - default value,

UrlType::ONCE - to limit deep linking behavior of the generated link to a single use,

UrlType::MARKETING_TYPE - to make the link show up under Marketing page in the dashboard

$link->setType(UrlType::MARKETING);

Configure custom data

For full description of possible $data options, please see: https://docs.branch.io/pages/links/integrate/#redirections

$data = [
     '$always_deeplink' => true,
     '$deeplink_path' => 'open?action_id=1234',
     
     '$ios_url' => 'http://MyAppURL.com/ios',
     '$ipad_url' => 'http://MyAppURL.com/ipad',
     '$android_url' => 'http://MyAppURL.com/android',
     
     '$og_app_id' => '1234',
     '$og_title' => 'My App',
     '$og_description' => 'My app\'s description.',
     '$og_image_url' => 'http://MyAppURL.com/image.png',
     
     'mydata' => 'something',
     'foo' => 'bar',
];
 
$link->setData($data);

Create link

To create the configured link, just call the createLink method and pass the Link' instance

$client = new \Iivannov\Branchio\Client(KEY, SECRET);
$client->createLink($link);

Update link

To update an already existing link you need to pass the url of the link and the updated Link instance to the updateLink method

$client = new \Iivannov\Branchio\Client(KEY, SECRET);
$link = $client->getLink($url);
$link->setChannel('bar');
$client->updateLink($url, $link);

Usage with Laravel

If you are using Laravel, the package contains a Service Provider and a Facade for you.

1. First you need to add the ServiceProvider and Facade classes in your config\app.php

'providers' => [
    ...
    Iivannov\Branchio\Integration\Laravel\BranchioServiceProvider::class,
];

'aliases' => [
    ...
    'Branchio' => Iivannov\Branchio\Integration\Laravel\Facade\Branchio::class
];

1. Then you need to add your username and password in config\services.php

'branchio' => [
    'key' => YOUR_BRANCHIO_KEY,
    'secret' => YOUR_BRANCHIO_SECRET
]

1. You are ready to go, just use the facade:

Branchio::getLink($url)
Branchio::createLink($link')
Branchio::updateLink($url, $link)

License

The MIT License (MIT). Please see License File for more information.