Trackerific <img src=“https://badge.fury.io/rb/trackerific.png” alt=“Gem Version” /> <img src=“https://travis-ci.org/travishaynes/trackerific.png” /> <img src=“https://coveralls.io/repos/travishaynes/trackerific/badge.png” alt=“Coverage Status” />

Package tracking in a gem. Currently supported carriers are:

FedEx
UPS
USPS

Prerequisites

You will need to sign up to each carrier you wish to utilize. They each have their own requirements and license agreements, so it’s up to you to make sure you follow their terms of agreement. For example, at the time this was written UPS requires that you include their logo on your website when you use their API.

You’ll also need the proper credentials from each carrier, which requires signing up through their individual websites, and is not always free, depending on which portion of their API you plan on using. Trackerific focuses primarily on the tracking APIs, so that’s all you’ll need to use this gem, unless you plan on implementing additional features.

Installation

To use this gem, add this line to your Gemfile

gem 'trackerific'

and then run

bundle install

Configuration

You will need to configure the credentials for each service you’re utilizing. Services without credentials will not be accessed by the gem.

Trackerific.configure do |config|
  config.fedex  = { key: 'key', password: 'password', account_number: 'acct',
                    meter_number: '123' }
  config.ups    = { key: 'key', user_id: 'userid', password: 'secret' }
  config.usps   = { user_id: 'userid' }
end

Tracking with Automatic Service Discovery

Once you configured the services, tracking a package is as easy as

details = Trackerific.track("package id")

Finding a Tracking Service Provider

If you do not know the tracking service provider of a package id you can use Trackerific::Services.find_by_tracking_id:

Trackerific::Services.find_by_tracking_id("123456789012")
Trackerific::Services.find_by_tracking_id("1Z12345E0291980793")
Trackerific::Services.find_by_tracking_id("EJ958083578US")

Each of the above examples will return an Array of Trackerific::Service::Base subclasses that are capable of tracking the given package ID.

Tracking a Package with a Specific Service

Use this method if you need to specify exactly which service to track a package.

details = Trackerific::Services::FedEx.track('123456789012')

Using #track will automatically read the credentials from Trackerific.config. If you need to assign them manually, use #new:

fedex = Trackerific::Services::FedEx.new(
  :account  => "account",
  :meter    => "123456789"
)
details = fedex.track('183689015000001')

Tracking Details

The tracking information is returned in a Trackerific::Details instance.

details.summary - Summary of the tracking events details.events - Array of Trackerific::Events

Tracking Events

Tracking::Details has an events Array with the following properties:

event.date - The date the package was shipped. event.date - The date/time of the event. event.description - Description of an event. event.location - The location of the package during that event.

Note that events are in last-in-first-out order, so the last event will always be the first event the carrier supplied.

Exception handling

Exception handling is esssential for tracking packages. If, for example, you enter the wrong number, or the tracking provider has yet to have added the tracking number to their system, a Trackerific::Error will be raised. Here’s an example on how to handle Trackerific::Errors:

begin
  details = Trackerific.track('EJ958083578US')
  # handle details here
rescue Trackerific::Error => e
  puts e.message
end

Testing

Trackerific provides a mocked service you can use in your unit tests of your application. You must require the service manually.

require 'trackerific/services/mock_service'
# Get a populated Trackerific::Details
details = Trackerific.track("XXXXXXXXXX")
# Throw a Trackerific::Error exception
details = Trackerific.track("XXXxxxxxxx")

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am ‘Add some feature’)
Push to the branch (git push origin my-new-feature)
Create new Pull Request