Bluevia client module definition

Introduction

   Bluevia Ruby SDK allows you to use the BueVia public API from your Ruby
   application using just a few lines of code.
   You only need to download the SDK, include it into your LOAD_PATH directory
   and leave magic work for you. If you download the gem this should be
   automatically included in your gem local repository.

   When you want to use as developer Bluevia public APIs,
   first of all you need to get a commercial or testing API Key.

   Ruby SDK wraps any request to BlueVia endpoint by using a generic object
   BlueviaClient. This object uses the Component Pattern to fetch any service
   required by the developer (oAuth, SMS or Directory).

Getting Started

   Find below the gem dependencies required by Bluevia SDK:

    - httpclient: used to create HTTP requests
    - oauth: generic gem to launch the oAuth process
    - nokogiri: used to parse XML responses (Advertising)
    - json_pure: used to parse JSON responses

   This snippet shows the easier way to create a new object with valid credentials
   that identify the application:

       require 'rubygems'
       require 'bluevia'
       include Bluevia

       @bc = BlueviaClient.new(
          { :consumer_key   => CONSUMER_KEY,
            :consumer_secret=> CONSUMER_SECRET,
            :uri            => "https://api.bluevia.com"
          })

Endpoints

   BlueVia has two endpoints, commercial and sandbox.
   Commercial is linked to Telefonica network, and sandbox is used just to
   verify application behavior.
   The developer can change the endpoint just setting the desired behavior
   in the client:

      @bc.set_commercial
      @bc.set_sandbox

   Use the method @bc.commercial? to verify if the client is accessing either
   commercial or sandbox endpoint.

Using Oauth

   User authentication is launched using oAuth protocol, so user is not
   required to use credentials in third party applications.
   If you want to learn more about oAuth please check this URL: http://oauth.net.

   When user wants to launch the oAuth process, once the Bluevia client object
   has been created only the two lines below are required to retrieve 
   a valid token for user:

       @service = @bc.get_service(:oAuth)
       token, secret, url = @service.get_request_token({:callback =>"http://foo.bar"})

   The retrieved parameter token and secret should be used during the oAuth
   process, and url is the endpoint where Bluevia shall authenticate the user.
   In case of a Rails application, the lines below could be used:

       token, token_secret, url = @service.get_request_token(
                               "http://foo.bar/bluevia/get_access")
       cookies[:token] = "#{token}|#{token_secret}"
       redirect_to(url)

   Both tokend and token_secret must be saved by the application provider
   because oAuth process will require it later.

   Once user is authenticated and she has authorized the application in 
   BlueVia portal, she should be redirected to the URL used as parameter before.
   Now it's time to fetch the valid token and token secret that shall identify
   the new user during any call to BlueVia API. Lines below show an example using Rails:

       def get_access
           oauth_verifier = params[:oauth_verifier]
           get_token_from_cookie
           @bc = BlueviaClient.new(
           { :consumer_key   => CONSUMER_KEY,
            :consumer_secret=> CONSUMER_SECRET
           })
           @service = @bc.get_service(:oAuth)
           @token, @token_secret = @service.get_access_token(@request_token, @request_secret, oauth_verifier)
       end

       private
           def get_token_from_cookie
               cookie_token = cookies[:token]
               unless cookie_token.nil?
               cookie_token = cookie_token.split("|")
               if cookie_token.size != 2
                   raise SyntaxError, "The cookie is not valid"
               end
               @request_token = cookie_token[0]
               @request_secret = cookie_token[1]
           end
       end

Using BlueviaClient to launch requests

   Most of requests when accessing Bluevia API are associated to a specific user,
   so when a BlueviaClient object is created both user token and 
   user token secret must be provided to identify user on behalf of
   whom the application wants to access BlueVia APIs.

       @bc = BlueviaClient.new(
          { :consumer_key   => CONSUMER_KEY,
            :consumer_secret=> CONSUMER_SECRET,
            :token          => USER_TOKEN,
            :token_secret   => TOKEN_SECRET,
            :uri            => "https://api.bluevia.com"
          })

Send a SMS

   First of all, create the BlueviaClient object as shown before.

   Any operation available in BlueviaClient object is associated to 
   a specific service. Each service represents a specific enabler provided by Bluevia.

   In case of SMS, these two lines are required to send a SMS on behalf of the user:

       @service = @bc.get_service(:Sms)
       info = @service.send_sms("11111", 
                                USER_TOKEN,
                                "Yet another SMS Text")

Request Directory Info

   @service = @bc.get_service(:Directory)
   response = @service.get_user_info(USER_TOKEN, Directory::USER_IDENTITIES)

Get Ad

   With Advertising API a developer can fetch an ad to include in her application.

   There are some required parameters:
          - user_agent
          - ad_request_id
          - ad_space

   And also optional parameters:
          - ad_presentation
          - ad_presentation_size
          - keywords
          - protection_policy

   All parameters should be include in a single Hash object:

   @service = @bc.get_service(:Advertising)

   params = {
      :user_agent => "Mozilla 5.0",
      :ad_request_id => "a1x4zasg58",
      :ad_space => "1200",
      :keywords => "bar"
   }

   ad = @service.request(params)