Giter VIP home page Giter VIP logo

branchio's Introduction

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.

Codacy Maintainability Packagist License Version


Table of Contents

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

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);    

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.

branchio's People

Contributors

ethanpooley avatar iivannov avatar samy avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar

branchio's Issues

BranchioForbiddenException

Hi I'm new to this package. I have no prior experience with the setup and usage of this package and I'm given the task to fix a bug, so please bear with me. What usually is the cause when BranchioForbiddenException is thrown? Branch secret and branch key are the same with that in the dashboard.

Guzzle 7 compatibility would be great

We're starting to run into library compatibility issues as we move forward to PHP8.1+. Specifically deprecation notices being thrown from the Guzzle 6 library. It would be good to the Branch.io client updated to support Guzzle 7. Might be as simple as a Composer change—Guzzle says that most users won't have to change code to upgrade.

adding meta data

Hi .. How can we add metadata to link without changing aliases? I Just want to add og meta data to existing links

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.