Installation¶ ↑

To use this gem, add this line to your Gemfile

gem 'trackerific'

and then run

bundle install

Usage¶ ↑

If you would like to see a functional example of this gem in action, check out the sample Rails app here: package-tracker

Configuration¶ ↑

To take advantage of Trackerific’s automatic service discovery, you will need to configure your credentials for each service.

# config/initializers/trackerific.rb
require 'trackerific'
Trackerific.configure do |config|
  config.fedex  :account  => 'account',
                :meter    => '123456789'

  config.ups    :key      => 'key',
                :user_id  => 'userid',
                :password => 'secret'

  config.usps   :user_id  => 'userid',
                :use_city_state_lookup => true
end

For USPS packages, the option :use_city_state_lookup defaults to false, and will only work if you have access to USPS’s CityStateLookup API. If you can enable it, this feature will provide the location for USPS package events.

Tracking with Automatic Service Discovery¶ ↑

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

include Trackerific
details = track_package "package id"

Finding a Tracking Service Provider¶ ↑

If you do not know the tracking service provider of a package id, or you used track_package, and you need to know which service was used to track it, you can use the tracking_service helper method.

include Trackerific
tracking_service "183689015000001"    # => Trackerific::FedEx
tracking_service "1Z12345E0291980793" # => Trackerific::UPS
tracking_service "EJ958083578US"      # => Trackerific::USPS
tracking_service "unknown package id" # => nil

Tracking a Package with a Specific Service¶ ↑

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

# Track a FedEx package:
fedex = Trackerific::FedEx.new :account => '123456789', :meter => '123456789'
details = fedex.track_package('183689015000001')

# Track a USPS package:
usps = Trackerific::USPS.new :user_id => '123USERID4567'
details = usps.track_package('EJ958083578US')

# Track a UPS package:
ups = Trackerific::UPS.new :user_id => 'userid', :key => 'kQdEJwuHBjtQ7g2', :password => 'secret'
details = ups.track_package('1Z12345E0291980793')

Tracking Details¶ ↑

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

details.summary # => a summary of the tracking events
details.events  # => an Array of Trackerific::Events

You can easily print out the tracking events just by doing:

puts details.events         # for all the events
puts details.events.first   # for just one event

Or, if you need specific information about an event:

details.events.last.date         # => the date the package was shipped
details.events.first.date        # => the last date the package was updated
details.events.first.description # => a description of an event
details.events.first.location    # => the location of the package during that event

location will not work for USPS packages, because USPS does not provide that information seperately from the description. So for USPS packages, the location will always be at the end of the description.

Note that events.last will return the first event the tracking provider supplied. This is because the events are listed in LIFO order, so the most recent events will always be at the top of the list.

City / State Lookup Via USPS¶ ↑

If you have access to the USPS CityStateLookup API, you can use Trackerific to look up the city and state of a zipcode.

usps = Trackerific::USPS.new :user_id => 'userid'
usps.city_state_lookup "90210" # => { :city => 'BEVERLY HILLS', :state => 'CA', :zip => '90210' }

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
  usps.track_package('EJ958083578US')
rescue Trackerific::Error => e
  puts e.message
end

or for a Rails application:

# in app/controllers/application_controller.rb
rescue_from Trackerific::Error do |exception|
  redirect_to root_url, :alert => exception.message
end

Writing a Custom Service¶ ↑

See the examples folder for an example of a custom service.

Testing with Trackerific¶ ↑

Trackerific provides a mocked service you can use in your unit tests of your application. The mocked service will be available in development and test environments only, and disabled in production.

details = track_package("XXXXXXXXXX") # => returns a populated Trackerific::Details
details = track_package("XXXxxxxxxx") # => throws a Trackerific::Errror exception

Contributing to trackerific¶ ↑

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet

• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it

• Fork the project

• Start a feature/bugfix branch

• Commit and push until you are happy with your contribution

• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright¶ ↑

Copyright © 2011 Travis Haynes. See LICENSE.txt for further details.