Skip to content
This repository has been archived by the owner on Jan 3, 2024. It is now read-only.
/ branch_io Public archive
forked from ushu/branch_io

Client for branch.io public API

License

Notifications You must be signed in to change notification settings

drync/branch_io

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

17 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

A Ruby wrapper for the branch.io public API

Gem Downloads License

Please see the Branch documentation for general information. Please report any problems by opening issues in this repo.

This is a simple HTTparty-based gem for accessing the branch.io REST APIs, as described here. See the Branch API documentation for further details.

It follows the exact design of the original REST API: basically links are resources you can generate and update, provided you hold the required credentials.

BEWARE: this gem does not (yet) cover all the API calls of the API, for now on only the link creation/update is supported

Installation

Add this line to your application's Gemfile:

gem 'branch_io'

And then execute:

$ bundle

Or install it yourself as:

$ gem install branch_io

Basic Usage

To access the APIs, you need to create a BranchIO::Client instance, passing in your branch.io key and your branch.io secret respectively.

# Create a new client
> client = BranchIO::Client.new("key_test_xxx", "secret_test_yyyy")
=> #<BranchIO::Client:0x007f8e7192a2a0 @branch_key="key_test_xxx", @branch_secret="secret_test_yyy">

# Ask the server for a new link
> res = client.link(feature: "test")
=> #<BranchIO::Client::UrlResponse:0x007f8e718c6a20 @response="...">

# Check for success and print the URL
> if res.success?
    puts res.url
  end
https://uym7.test-app.link/ABCDEFG...

Please not that the gem reads the BRANCH_KEY and BRANCH_SECRET environment variables by default, and provided these are defined passing them to the client is optional:

# Provided BRANCH_KEY and BRANCH_SECRET are defined
> client = BranchIO::Client.new
=> #<BranchIO::Client:... @branch_key="key_test_xxx", @branch_secret="secret_test_yyy">

Similarly all the methods of the "default" client (the one without arguments) are made available on the module itself:

# Provided BRANCH_KEY and BRANCH_SECRET are defined
> res = BranchIO.link(feature: "test") # <= same as BranchIO.new.link(...)
=> #<BranchIO::Client::UrlResponse:0x007f8e718c6a20 @response="...">

Available API calls

Client#link and Client#link!: Registers a new deep linking URL

This method registers a new deep linking URL to the branch.io service. The arguments are passed to a new instance of BranchIO::LinkProperties.

# Call the service
res = client.link(
  feature: "test",
  channel: "test",
  campaign: "test",
  stage: 1,
  alias: "testsingle",
  type: "test",
  tags: [ "test" ],
  data: {
    test: true
  }
)

# Inspect the server response
if res.success?
  puts "Successfully created URL: #{res.url}"
else
  puts "Error creating URL: #{res.error}"
end

The only difference between #link and #link! is that the latter version will raise a new BranchIO::ErrorApiCallFailed exception in case of an error.

Client#links and Client#links!: Registers a bulk of deep linking URLs

This method registers a bulk deep linking URLs to the branch.io service. The arguments are passed to a new instances of BranchIO::LinkProperties.

# Call the service
url_configs = [
  { feature: "test" }, # First link
  { feature: "test", stage: 2 } # second link
  # etc..
]
res = client.links(url_configs)

# Inspect the server response
if res.success?
  puts "Successfully created #{res.urls.count} URLs: #{res.urls.join(',')}"
else
  puts "Error creating URLs: #{res.errors.join(',')}"

  # There has been errors, but some URLs might be valid
  if res.urls.count > 0
      puts "Successfully created #{res.urls.count} URLs out of #{url_configs.count}: #{res.urls.join(',')}"
  end
end

The only difference between #links and #links! is that the latter version will raise a new BranchIO::ErrorApiCallFailed exception in case of an error.

Client#link_info and Client#link_info!: Registers a new deep linking URL

BEWARE: this method requires the BRANCH_SECRET to be defined

This method queries an existing link URL for its properties.

# Call the service
res = client.link_info("https://...")

# Inspect the server response
if res.success?
  puts "Successfully retrieved link info: #{res.link_properties.to_json}"
else
  puts "Error retrieving link info: #{res.error}"
end

The only difference between #link_info and #link_info! is that the latter version will raise a new BranchIO::ErrorApiCallFailed exception in case of an error.

Client#update_link and Client#update_link!: Registers a new deep linking URL

BEWARE: this method requires the BRANCH_SECRET to be defined

This method updates the properties of an existing link and returns the new updated set of properties.

# Call the service
res = client.update_link("https://...", stage: 3)

# Inspect the server response
if res.success?
  puts "Successfully updated link info: #{res.link_properties.to_json}"
else
  puts "Error updating link info: #{res.error}"
end

The only difference between #update_link and #update_link! is that the latter version will raise a new BranchIO::ErrorApiCallFailed exception in case of an error.

Client#event and Client#event!:

Logs one of the following events:

This method logs an event to the branch.io service. The arguments are passed to a new instance of BranchIO::EventProperties.

# Call the service
res = client.event(
  name: "PURCHASE",
  user_data: {
    os: "iOS",
    os_version: "11.0.1",
    environment: "FULL_APP",
    developer_identity: "1",
    app_version: "1.0.1"
  },
  custom_data: {
    purchase_location: "Joes Liquor Barn",
    store_pickup: "unavailable"
  },
  event_data: {
    currency: "USD",
    shipping: 5,
    tax: 0,
    revenue: 35,
    transaction_id: "Order-11"
  },
  content_items: [
    {
      "$content_schema"   => "COMMERCE_PRODUCT",
      "$price"            => 100,
      "$quantity"         => 2,
      "$sku"              => "112320",
      "$product_name"     => "Domaine de la Romanee-Conti Romanee-Conti Grand Cru 1990.",
      "$product_category" => "FOOD_BEVERAGES_AND_TOBACCO",
      "$product_variant"  => "750ml Current Vintage"
    }
  ]
)

# Inspect the server response
if res.success?
  puts "Successfully created URL: #{res.url}"
else
  puts "Error creating URL: #{res.error}"
end

The only difference between #event and #event! is that the latter version will raise a new BranchIO::ErrorApiCallFailed exception in case of an error.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ushu/branch_io. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

TODO

  • Add support for the /app API calls
  • Add some docs to the code
  • Write a better README...

License

The gem is available as open source under the terms of the MIT License.

About

Client for branch.io public API

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Ruby 99.5%
  • Shell 0.5%