ruby script/plugin install git://github.com/nbibler/devpay.git

Examples
============

Lets say you're loading up your credentials into a global constant hash called AWS_CREDS, and you've stored your product identifiers into an ActiveRecord ‘Product' model as product_code, product_token, and offer_code, respectively.

Setting Your Credentials

You can globally set your credentials, like so:

    Devpay.access_key_id      = AWS_CREDS[:access_key_id]
    Devpay.secret_access_key  = AWS_CREDS[:secret_access_key]

Or, you can pass your credentials as optional parameters to each Devpay method call you make:

    Devpay.active?(pid, product_code, AWS_CREDS[:access_key_id], AWS_CREDS[:secret_access_key])

Product URLs
================
If you've got an object which responds to :offer_code, you can:

    <%= link_to 'Buy Now', Devpay.purchase_url_for(product) %>

Otherwise, you can pass the offer code directly:

    <%= link_to 'Buy Now', Devpay.purchase_url_for('ABCD1234') %>

See Devpay.purchase_url_for for more information.

Activation
==================

Once the user comes back to your site, you'll get an Activation Key and a Product Code. If you're unlucky and the redirection failed, you may have to query your customer for these values, directly (probably a pull-down for the products would be better than asking for that one).

In your DevPayResponseController, you could:

    # This URL was set in your DevPay product as the return URL (i.e. http://www.example.com/devpay_response/returned)
    def returned
      if product                  = Product.find_by_product_code(params['ProduceCode'])
        activation_response       = Devpay.activate!(params['ActivationKey'], product)
        PaidUser.create!({
          ...
          :user_token             => activation_response.user_token,
          :persistent_identifier  => activation_response.persistent_identifier,
          ...
        })
      else
        # Handle unrecognized Product Code here.
      end
    end

See Devpay.activate! for more information

Query for Active Product Codes
=======================
You could request a list of all active products which a customer is utilizing by your DevPay services:

    Devpay.find_all_product_codes_for(paid_user)      #=> [ "ABCD1234", "ABCD1235" ]

In the above example, we're assuming paid_user responds with the correct persistent identifier when :persistent_identifier is called against it. See Devpay.find_all_product_codes_for for more information.


Subscription State
================
As Amazon does not alert you to changes in DevPay subscription states (like PayPal's Instant Payment Notification service, for example), it is up to you to periodically determine the state of the customer's subscription. This can be done with the following:

    Devpay.active?(paid_user, product_paid_for)       #=> true
    Devpay.active?(paid_user, product_not_paid_for)   #=> false

In the above example, we're assuming paid_user responds with the correct persistent identifier when :persistent_identifier is called against it. Further, we're also assuming that product is an object which responds to :product_code and returns a valid DevPay product code. See Devpay.active? for more information.

Notable, Miscellaneous Information

Raised Exceptions
===============
All exceptions raised by this plugin inherit from Devpay::Error (a type of Exception). So, in general, a

    rescue Devpay::Error => e
      puts "Devpay had a problem: #{e.class} '#{e.message}'"

Should catch any and all problems raised through the use of this plugin. More specific errors are nearly always raised, however. Nearly a hundred more specific errors are not publicly documented, but can be found in lib/errors/errors.rb and lib/errors/license_service/errors.rb.

Request Throttling
===================

The Amazon License Service (used for activating and verifying DevPay subscriptions) may enter periods of request throttling. During these periods the service will respond with HTTP 503 Service Unavailable. Amazon's documentation states that you should retry these requests, but fails to stipulate a retry delay. This implementation defaults the delay period to a half-second. :)

More information can be found in the documentation for Devpay::LicenseService.

There is currently no advanced documentation for this plugin.