Branch Metrics (Branch.io) HTTP API Client
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., (*1)
, (*2)
Table of Contents, (*3)
Important Notice
The latest versions after 1.1.x are not backwards compatible with the old versions 1.0.x., (*4)
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, (*5)
Installation
The package can be installed with Composer. Just run this command:, (*6)
``` bash
$ composer require iivannov/branchio, (*7)
## Basic usage
### Get link data
``` php
$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
Link instance contains all the configurable options for a Branch Metrics link and provides method to set them., (*8)
$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, (*9)
| Key |
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 to replace of the standard encoded short URL. Link aliases must be unique (a 409 error will occur if you create an alias already taken). Appending a / will break the alias. bnc.lt link domain alias links are incompatible with Universal Links and Spotlight. |
| type |
Must be an int. Set to 1 to limit deep link to a single use. Set to 2 to make the link show up under Quick Links while adding $marketing_title to data. Does not work with the Native SDKs |
$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);
You can easily set the deep linking behaviour by passing the type parameter. You have the following options:, (*10)
UrlType::DEFAULT_TYPE - default value,, (*11)
UrlType::ONCE - to limit deep linking behavior of the generated link to a single use,, (*12)
UrlType::MARKETING_TYPE - to make the link show up under Marketing page in the dashboard, (*13)
$link->setType(UrlType::MARKETING);
For full description of possible $data options, please see:
https://docs.branch.io/pages/links/integrate/#redirections, (*14)
$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, (*15)
``` php
$client = new \Iivannov\Branchio\Client(KEY, SECRET);
$client->createLink($link);, (*16)
### 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);, (*17)
## 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,
];, (*18)
'aliases' => [
...
'Branchio' => Iivannov\Branchio\Integration\Laravel\Facade\Branchio::class
];, (*19)
2. Then you need to add your username and password in `config\services.php`
'branchio' => [
'key' => YOUR_BRANCHIO_KEY,
'secret' => YOUR_BRANCHIO_SECRET
], (*20)
3. You are ready to go, just use the facade:
Branchio::getLink($url)
Branchio::createLink($link')
Branchio::updateLink($url, $link)
```, (*21)
License
The MIT License (MIT). Please see License File for more information., (*22)
Wallogit.com
