opentok 0.1.2 → 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0122202a607892b2550a526dc44c35b2beea87c8
+  data.tar.gz: b005eb0fba4ee0bdcec3123c87042936ff70673e
+SHA512:
+  metadata.gz: 7a15810ae54376c9442277c4cfd33ca3532378b5b0093a961cc6781734adf747f90771286fece4e428ecbcf143453152211f775ae1b99ef147031a7a4f5bec75
+  data.tar.gz: e85e3a3832c6984c7ec975e6acba8ff45669e8287f009fea12d7ec1ff77f6f0bc77c99f8bb12cbf4edd0438ebb985ebbb17629003028a02e44de1f39008150bf

data/README.md

@@ -1,7 +1,8 @@
-# Opentok
+# OpenTok Server SDK for Ruby
+
+The OpenTok server SDK for Ruby lets you generate [sessions](http://tokbox.com/opentok/tutorials/create-session/) and
+[tokens](http://tokbox.com/opentok/tutorials/create-token/) for [OpenTok](http://www.tokbox.com/) applications.
 
-OpenTok is an API from TokBox that enables websites to weave live group video communication into their online experience. Check out <http://www.tokbox.com/> for more information.  
-This is the official OpenTok Ruby Server SDK for generating Sessions, Tokens, and retriving Archives. Please visit our [getting started page](http://www.tokbox.com/opentok/tools/js/gettingstarted) if you are unfamiliar with these concepts.  
 
 ## Installation
 
@@ -12,136 +13,57 @@ gem 'opentok'
 
 To install as a regular gem just type `gem install opentok`
 
+
 ## Requirements
 
-You need an api-key and secret. Sign up at <http://www.tokbox.com/opentok/tools/js/apikey>.
+The OpenTok server SDK for Ruby requires Ruby 1.9 or greater.
+
+You need an OpenTok API key and API secret, which you can obtain at <https://dashboard.tokbox.com>.
 
 # OpenTokSDK
 
 In order to use any of the server side functions, you must first create an `OpenTokSDK` object with your developer credentials.  
-`OpenTokSDK` takes 2 parameters:
-> key (string) - Given to you when you register  
-> secret (string) - Given to you when you register  
+`OpenTokSDK` takes two parameters:
+
+* key (string) - Given to you when you register  
+* secret (string) - Given to you when you register  
 
 <pre>
 # Creating an OpenTok Object
-API_KEY = ''                # should be a string
-API_SECRET = ''            # should be a string
+API_KEY = ''     # replace with your OpenTok API key
+API_SECRET = ''  # replace with your OpenTok API secret
 OTSDK = OpenTok::OpenTokSDK.new API_KEY, API_SECRET
 </pre>
 
-
 ## Creating Sessions
-Use your `OpenTokSDK` object to create `session_id`  
-`createSession` takes 1-2 parameters:
-> location (string) -  OPTIONAL. a location so OpenTok can stream through the closest server  
-> properties (object) - OPTIONAL. Set peer to peer as `enabled` or `disabled`. Disabled by default  
-
+Call the `createSession()` method of the `OpenTokSDK` object to create a session. The method returns a Session object.
+The `sessionId` property of the Session object is the OpenTok session ID:
 <pre>
-# creating a simple session: closest streaming server will be automatically determined when user connects to session
+# creating an OpenTok server-enabled session
 sessionId = OTSDK.createSession().to_s
 
-# Creating Session object, passing request IP address to determine closest production server
-sessionId = OTSDK.createSession( request.remote_ip ).to_s
-
-# Creating Session object with p2p enabled
-sessionProperties = {OpenTok::SessionPropertyConstants::P2P_PREFERENCE => "enabled"}    # or disabled
-sessionId = OTSDK.createSession( @location, sessionProperties ).to_s
+# Creating peer-to-peer session
+sessionProperties = {OpenTok::SessionPropertyConstants::P2P_PREFERENCE => "enabled"}
+sessionId = OTSDK.createSession( nil, sessionProperties ).to_s
 </pre>
 
 ## Generating Tokens
-With the generated sessionId, you can start generating tokens for each user.
-`generate_token` takes in hash with 1-4 properties:
-> session_id (string) - REQUIRED  
-> role (string) - OPTIONAL. subscriber, publisher, or moderator  
-> expire_time (int) - OPTIONAL. Time when token will expire in unix timestamp  
-> connection_data (string) - OPTIONAL. Metadata to store data (names, user id, etc)
+With the generated session ID, you can generate tokens for each user:
 
 <pre>
-# Generating a token
-token = OTSDK.generateToken :session_id => session, :role => OpenTok::RoleConstants::PUBLISHER, :connection_data => "username=Bob,level=4"
+# Generating a publisher token
+token = OTSDK.generateToken :session_id => sessionId
+ 
+# Generating a token with moderator role and connection data
+role = OpenTok::RoleConstants::MODERATOR
+connection_data = "username=Bob,level=4"
+token = OTSDK.generateToken :session_id => sessionId, :role => role, :connection_data => connection_data
 </pre>
 
 Possible Errors:
-> "Null or empty session ID are not valid"  
-> "An invalid session ID was passed"
-
-## Manipulating Archive Videos
-To Download or delete archived video, you must have an Archive ID which you get from the javascript library. If you are unfamiliar with archiving concepts, please visit our [archiving tutorial](http://www.tokbox.com/opentok/api/documentation/gettingstartedarchiving)  
-
-## Delete Archives
-OpenTok SDK has a function `deleteArchive` that lets you delete videos in a recorded archive. 
-Use your `OpenTokSDK` object to call `deleteArchive`
-`deleteArchive` takes in 2 parameters and returns a true or false boolean representing the success of the delete request
-> archive_id (string) - REQUIRED  
-> token (string) - REQUIRED. This token MUST have a moderator role, and it should be generated with the same session_id used to create the archive  
-> **returns**  
-  true: Success, the archive is deleted  
-  false: Archive does not exist (perhaps it was already deleted or never created), invalid token (perhaps it does not have the moderator role or it's generated with the wrong session_id)
-
-Example:
-<pre>
-successful = OTSDK.deleteArchive( archive_id, token )
-</pre>
-
-# Stitching Archives
-OpenTok SDK allows you to stich up to 4 videos together in an archive.  
-Use your `OpenTokSDK` object to call stitchArchive  
-stitchArchive takes in 1 parameter and returns a hash object with code, message, and location if stitch is successful.  
-> archive_id (string) - REQUIRED  
-> **returns**:  
-  {:code=>201, :message=>"Successfully Created", :location=>response["location"]}  
-  {:code=>202, :message=>"Processing"}  
-  {:code=>403, :message=>"Invalid Credentials"}  
-  {:code=>404, :message=>"Archive Does Not Exist"}  
-  {:code=>500, :message=>"Server Error"}  
-
-Example:  
-<pre>
-result = OTSDK.stitchArchive archive_id
-if result[:code] == 201
-  return result[:location]
-end
-</pre>
 
-# Get Archive Manifest
-With your **moderator token** and OpentokSDK Object, you can generate OpenTokArchive Object, which contains information for all videos in the Archive  
-`getArchiveManifest()` takes in 2 parameters: **archiveId** and **moderator token**  
-> archive_id (string) - REQUIRED. 
-> token (string) - REQUIRED. 
-> **returns** an `OpenTokArchive` object.  
-  The *resources* property of this object is array of `OpenTokArchiveVideoResource` objects, and each `OpenTokArchiveVideoResource` object represents a video in the archive.
-
-Example:(Make sure you have the OpentokSDK Object)
-<pre>
-@token = '...'  # token generated with corresponding session
-@archiveId = '5f74aee5-ab3f-421b-b124-ed2a698ee939' #Obtained from Javascript Library
-otArchive = OTSDK.getArchiveManifest(@archiveId, @token)
-</pre>
-
-# Get video ID
-`OpenTokArchive.resources` is an array of `OpenTokArchiveVideoResource` objects. OpenTokArchiveVideoResource has `getId()` method that returns the video_id  
-`getId()` will return the video ID (a String)
-
-Example:
-<pre>
-otArchive = OTSDK.getArchiveManifest(@archiveId, @token)
-otVideoResource = otArchive.resources[0]
-videoId = otVideoResource.getId()
-</pre>
-
-# Get Download Url
-`OpenTokArchive` has `downloadArchiveURL` that will return an url string for downloading the video in the archive. You must call this function every time you want the file, because this url expires after 24 hours
-> video_id (string) - REQUIRED  
-> token (string) - REQUIRED  
-> returns url string
-
-Example:
-<pre>
-url = otArchive.downloadArchiveURL(video_id, token)
-</pre>
-
------
+* "Null or empty session ID are not valid"  
+* "An invalid session ID was passed"
 
 # Contributing
 To contribute, simple fork this repository and send a pull request when you are done.  
@@ -151,10 +73,9 @@ To install necessary gems, type `bundle install` in the root directory.
 
 To run test cases, type `rspec spec/` in the root directory.   
 
------
 
-### Fun Fact:
+# More information
+
+See the [reference documentation](doc/reference.md).
 
-To upload opentok gem, first update `opentok.gemspec` specs  
-Build gem: `gem build opentok.gemspec`  
-Push gem: `gem push opentok-*.gem`    
+For more information on OpenTok, go to <http://www.tokbox.com/>.

data/doc/reference.md

@@ -0,0 +1,122 @@
+OpenTok Ruby SDK reference
+==========================
+
+You need to instantiate an OpenTokSDK object before calling any of its methods.
+To create a new OpenTokSDK object, call the OpenTokSDK constructor with the API key
+and the API secret TokBox issued you. (You get an API key when you
+<a href="https://dashboard.tokbox.com/users/sign_in">sign up</a> for an OpenTok account.) Do not reveal
+your API secret string. You use it with the OpenTokSDK constructor (only on your web
+server) to create OpenTok sessions.
+
+    API_KEY = ''               # should be a string
+    API_SECRET = ''            # should be a string
+    OTSDK = OpenTok::OpenTokSDK.new API_KEY, API_SECRET
+
+create_session() method
+-----------------------
+The `create_session()` method of the OpenTokSDK object to create a new OpenTok
+session and obtain a session ID.
+
+The `create_session()` method has the following parameters:
+
+* `location` (String) &mdash; An IP address that TokBox will use to situate the session in its global network.
+  In general, you should not pass in a location hint (or pass in nil); if no location hint is passed in, the session
+uses a media server based on the location of the first client connecting to the session. Pass a location hint in only
+if you know the general geographic region (and a representative IP address) and you think the first client connecting
+may not be in that region.
+
+* `properties` (Object) &mdash; Optional. An object used to define
+peer-to-peer preferences for the session. The `properties` option includes one property &mdash;
+`p2p.preference` (a string). This property determines whether the session's streams will
+be transmitted directly between peers. You can set the following possible values:
+
+  * "disabled" (the default) &mdash; The session's streams will all be relayed using the OpenTok media server.
+    <br><br>
+    **In OpenTok v2:** The <a href="http://www.tokbox.com/blog/mantis-next-generation-cloud-technology-for-webrtc/">OpenTok
+media server</a> provides benefits not available in peer-to-peer sessions. For example, the OpenTok media server can
+decrease bandwidth usage in multiparty sessions. Also, the OpenTok server can improve the quality of the user experience
+through <a href="http://www.tokbox.com/blog/quality-of-experience-and-traffic-shaping-the-next-step-with-mantis/">dynamic
+traffic shaping</a>. For information on pricing, see the <a href="http://www.tokbox.com/pricing">OpenTok pricing page</a>.
+
+  * "enabled" &mdash; The session will attempt to transmit streams directly between clients.
+    <br><br>
+    **In OpenTok v1:** Peer-to-peer streaming decreases latency and improves quality. If peer-to-peer streaming
+fails (either when streams are initially published or during the course of a session), the session falls back to using
+the OpenTok media server to relaying streams. (Peer-to-peer streaming uses UDP, which may be blocked by a firewall.)
+For a session created with peer-to-peer streaming enabled, only two clients can connect to the session at a time.
+If an additional client attempts to connect, the TB object on the client dispatches an exception event.
+
+
+The `create_session` method returns a Session object. This
+object includes a `sessionID` property, which is the session ID for the
+new session. For example, when using the OpenTok JavaScript library, use this
+session ID in JavaScript on the page that you serve to the client.
+The JavaScript will use this value when calling the `connect()`
+method of the Session object (to connect a user to an OpenTok session).
+
+OpenTok sessions do not expire. However, authentication tokens do expire (see the next section on the
+generate_token() method.) Also note that sessions cannot explicitly be destroyed.
+
+Calling the `create_session()` method results in an `OpenTokException`
+in the event of an error. Check the error message for details.
+
+Here is a simple that creates a OpenTok server-enabled session:
+
+    sessionId = OTSDK.createSession().to_s
+
+Here is an example that creates a peer-to-peer session:
+
+    sessionProperties = {OpenTok::SessionPropertyConstants::P2P_PREFERENCE => "enabled"}
+    sessionId = OTSDK.createSession( nil, sessionProperties ).to_s
+
+You can also create a session using the <a href="http://www.tokbox.com/opentok/api/#session_id_production">OpenTok
+REST API</a> or the <a href="https://dashboard.tokbox.com/projects">OpenTok dashboard</a>.
+
+
+generate_token() method
+-----------------------
+
+In order to authenticate a user connecting to a OpenTok
+session, a user must pass an authentication token along with the API key.
+
+The method has the following parameters:
+
+* `session_id` (String) &mdash; The session ID corresponding to the session to which the user will connect.
+
+* `role` (String) &mdash; Optional. Each role defines a set of permissions granted to the token.
+Valid values are defined in the RoleConstants class in the server-side SDKs:
+
+  * `SUBSCRIBER` &mdash; A subscriber can only subscribe to streams.</li>
+  
+  * `PUBLISHER` &mdash; A publisher can publish streams, subscribe to streams, and signal.
+    (This is the default value if you do not specify a value for the `role` parameter.)</li>
+   
+  * `MODERATOR` &mdash; In addition to the privileges granted to a publisher, a moderator
+    can call the `forceUnpublish()` and `forceDisconnect()` method of the
+    Session object.</li>
+
+* `expire_time` (int) &mdash; Optional. The time when the token
+will expire, defined as an integer value for a Unix timestamp (in seconds).
+If you do not specify this value, tokens expire in 24 hours after being created.
+The `expiration_time` value, if specified, must be within 30 days
+of the creation time.
+
+* `connection_data` (String) &mdash; Optional. A string containing metadata describing the connection.
+For example, you can pass the user ID, name, or other data describing the connection.
+The length of the string is limited to 1000 characters.
+
+Calling the `generate_token()` method returns the token string.
+
+The following code example shows how to obtain a publisher token:
+
+    token = OTSDK.generateToken :session_id => sessionId
+
+The following PHP code example shows how to obtain a token that has a role of "moderator" and that has
+a connection metadata string:
+
+    role = OpenTok::RoleConstants::MODERATOR
+    connection_data = "username=Bob,level=4"
+    token = OTSDK.generateToken :session_id => sessionId, :role => role, :connection_data => connection_data
+
+For testing, you can also use the <a href="https://dashboard.tokbox.com/projects">OpenTok dashboard</a>
+page to generate test tokens.

data/lib/open_tok/exception.rb

@@ -11,8 +11,7 @@ module OpenTok
   # The exception that gets thrown when an invalid api-key and/or secret is given.
   class OpenTokException < RuntimeError
 
-    def initialize(code, message)
-      @code = code
+    def initialize(message)
       @mesasge = message
     end
 
@@ -29,11 +28,9 @@ module OpenTok
       # Generates the relevant exception instance based on the XML error data received
       def from_error(error)
         child = error.get_elements('Errors')[0].get_elements('error')[0]
-        code = child.attributes['code']
-        exception = exceptions.find{|exc| exc.http_code == code }
         exception ||= self
         message = child.children.empty? ? '' : child.children[0].attributes['message']
-        exception.new code, message
+        exception.new message
       end
 
       # To be overriden by subclasses
@@ -50,4 +47,4 @@ module OpenTok
     end
   end
 
-end
+end

data/lib/open_tok/request.rb

@@ -44,9 +44,9 @@ module OpenTok
       end
 
     rescue Net::HTTPExceptions => e
-      raise OpenTokException.new e.response.code, "Unable to create fufill request: #{e}"
+      raise OpenTokException.new "Unable to create fufill request: #{e}"
     rescue NoMethodError => e
-      raise OpenTokException.new e.response.code, "Unable to create a fufill request at this time: #{e}"
+      raise OpenTokException.new "Unable to create a fufill request at this time: #{e}"
     end
 
     private

data/lib/open_tok/version.rb

@@ -1,5 +1,5 @@
 module OpenTok
 
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 
 end

data/sample/sample.rb

@@ -0,0 +1,26 @@
+require 'opentok'
+
+API_KEY = ''    # See https://dashboard.tokbox.com/
+API_SECRET = '' # See https://dashboard.tokbox.com/
+
+OTSDK = OpenTok::OpenTokSDK.new API_KEY, API_SECRET
+
+# Create an OpenTok server-enabled session
+sessionId = OTSDK.createSession().to_s
+print sessionId + "\n"
+
+# Create a peer-to-peer session
+sessionProperties = {OpenTok::SessionPropertyConstants::P2P_PREFERENCE => "enabled"}    # or disabled
+sessionId = OTSDK.createSession( nil, sessionProperties ).to_s
+print sessionId + "\n"
+
+# Generate a publisher token
+token = OTSDK.generateToken :session_id => sessionId
+print token + "\n"
+
+# Generate a token with moderator role and connection data
+role = OpenTok::RoleConstants::MODERATOR
+connection_data = "username=Bob,level=4, score=8888888888"
+token = OTSDK.generateToken :session_id => sessionId, :role => role, :connection_data => connection_data
+print token + "\n"
+

data/spec/cassettes/session.yml

@@ -14,7 +14,7 @@ http_interactions:
       Content-Type:
       - application/x-www-form-urlencoded
       X-Tb-Partner-Auth:
-      - 459782:b44c3baa32b6476d9d88e8194d0eb1c6b777f76b
+      - 459782:***REMOVED***
   response:
     status:
       code: 200

data/spec/cassettes/stitchArchive.yml

@@ -14,7 +14,7 @@ http_interactions:
       Content-Type:
       - application/x-www-form-urlencoded
       X-Tb-Partner-Auth:
-      - 459782:b44c3baa32b6476d9d88e8194d0eb1c6b777f76b
+      - 459782:***REMOVED***
   response:
     status:
       code: 201

data/spec/opentok_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 describe OpenTok do
 
   let(:api_key) { '459782' }
-  let(:api_secret) { 'b44c3baa32b6476d9d88e8194d0eb1c6b777f76b' }
+  let(:api_secret) { '***REMOVED***' }
   let(:api_url) { 'http://api.opentok.com/hl' }
   let(:host) { 'localhost' }
 
@@ -78,7 +78,7 @@ describe OpenTok do
   describe "Archiving downloads" do
     use_vcr_cassette "archives"
     let(:api_key) { '459782' }
-    let(:api_secret) { 'b44c3baa32b6476d9d88e8194d0eb1c6b777f76b' }
+    let(:api_secret) { '***REMOVED***' }
     let(:opentok) { OpenTok::OpenTokSDK.new api_key, api_secret, {:api_url=>""} }
     let(:opts) { {:partner_id => api_key, :location=>host} }
 
@@ -105,7 +105,7 @@ describe OpenTok do
   describe "Delete Archives" do
     use_vcr_cassette "deleteArchive"
     let(:api_key) { '459782' }
-    let(:api_secret) { 'b44c3baa32b6476d9d88e8194d0eb1c6b777f76b' }
+    let(:api_secret) { '***REMOVED***' }
     let(:opentok) { OpenTok::OpenTokSDK.new api_key, api_secret, {:api_url => ""} }
     let(:session) { '1_MX40NTk3ODJ-MTI3LjAuMC4xflR1ZSBTZXAgMDQgMTQ6NTM6MDIgUERUIDIwMTJ-MC41MjExODEzfg' }
     let(:token) { opentok.generateToken({:session_id => session, :role=>OpenTok::RoleConstants::PUBLISHER}) }
@@ -121,7 +121,7 @@ describe OpenTok do
   describe "stitch api" do
     use_vcr_cassette "stitchArchive"
     let(:api_key) { '459782' }
-    let(:api_secret) { 'b44c3baa32b6476d9d88e8194d0eb1c6b777f76b' }
+    let(:api_secret) { '***REMOVED***' }
     let(:opentok) { OpenTok::OpenTokSDK.new api_key, api_secret }
     let(:archiveId) { "200567af-0726-4e93-883b-fe0426d6310a" }