| Class | FireEagle::Client |
| In: |
lib/fireeagle/client.rb
|
| Parent: | Object |
| access_token | [R] | TODO add access_token=() and request_token=() methods that check whether the tokens are usable |
| consumer | [R] | TODO add access_token=() and request_token=() methods that check whether the tokens are usable |
| format | [R] | TODO add access_token=() and request_token=() methods that check whether the tokens are usable |
| request_token | [R] | TODO add access_token=() and request_token=() methods that check whether the tokens are usable |
Initialize a FireEagle Client. Takes an options Hash.
User-specific OAuth tokens tie FireEagle users to your application. As such, they are intended to be distributed (with keys) to that user‘s mobile device and/or computer running your desktop or mobile client. For web-based applications User-specific tokens will be retrieved by your web server where they should be treated as private data. Take care to avoid releasing this data to the public, as the corresponding User‘s location information may be inadvertently exposed. User-specific OAuth tokens should be considered the property of your users.
General-purpose OAuth tokens are tied to your application and allow you, as a developer, to make more general (often batch-style) queries against FireEagle. As a result, allowing this token/secret combination loose has the potential to reveal a much greater amount of personal data. In an attempt to mitigate this, we will only grant general-purpose tokens to web applications (contact us with details, if you seek an exception). In addition, we require developers to provide a restrictive IP range at registration time in order to further mitigate the risk of general-purpose tokens being used inappropriately.
In general, OAuth tokens should be considered sacrosanct in order to help us respect our users’ privacy. Please take this responsibility on as your own. If your Application Oauth tokens are compromised, FireEagle will turn off your application service until the problem is resolved.
If the Client is initialized without an OAuth access token, it‘s assumed you‘re operating a non-web based application.
For non web-based applications, such as a mobile client application, the authentication between the user and the application is slightly different. The request token is displayed to the user by the client application. The user then logs into the FireEagle website (using mobile_authorization_url) and enters this code to authorize the application. When the user finishes the authorization step the client application exchanges the request token for an access token (using convert_to_access_token). This is a lightweight method for non-web application users to authenticate an application without entering any identifying information into a potentially insecure application. Request tokens are valid for only 1 hour after being issued.
Initialize a client with your consumer key, consumer secret, and your mobile application id:
>> c = FireEagle::Client.new(:consumer_key => "key", :consumer_secret => "sekret", :app_id => 12345) => #<FireEagle::Client:0x1ce2e70 ... >
Generate a request token:
>> c.get_request_token => #<OAuth::Token:0x1cdb5bc @token="ENTER_THIS_TOKEN", @secret="sekret">
Prompt your user to visit your app‘s mobile authorization url and enter ENTER_THIS_TOKEN:
>> c.mobile_authorization_url => "http://fireeagle.yahoo.net/oauth/mobile_auth/12345"
Once the user has indicated to you that they‘ve done this, convert their request token to an access token:
>> c.convert_to_access_token => #<OAuth::Token:0x1cd3bf0 @token="access_token", @secret="access_token_secret">
You‘re done!
The URL the user must access to authorize this token. get_request_token must be called first. For use by web-based and desktop-based applications.
Exchange an authorized OAuth Request token for an access token. For use by desktop-based and mobile applications.
Disambiguates potential values for update query. Results from lookup can be passed to update to ensure that FireEagle will understand how to parse the Location Hash.
All three Location methods (lookup, update, and within) accept a Location Hash.
There is a specific order for looking up locations. For example, if you provide lat, lon, and address, FireEagle will use the the latitude and longitude geo-coordinates and ignore the address.
Location Hash keys, in order of priority:
Not yet supported:
Return the Fire Eagle authorization URL for your mobile application. At this URL, the User will be prompted for their request_token.
Query for Users of an Application who have updated their Location recently. Returns a list of Users for the Application with recently updated locations.
time The time to start looking at recent updates from. Value is flexible, supported forms are ‘now’, ‘yesterday’, ‘12:00’, ‘13:00’, ‘1:00pm’ and ‘2008-03-12 12:34:56’. (default: ‘now’) count Number of users to return per page. (default: 10) start The page number at which to start returning the list of users. Pages are 0-indexed, each page contains the per_page number of users. (default: 0)
Sets a User‘s current Location using using a Place ID hash or a set of Location parameters. If the User provides a Location unconfirmed with lookup then FireEagle makes a best guess as to the User‘s Location.
All three Location methods (lookup, update, and within) accept a Location Hash.
There is a specific order for looking up locations. For example, if you provide lat, lon, and address, FireEagle will use the the latitude and longitude geo-coordinates and ignore the address.
Location Hash keys, in order of priority:
Not yet supported:
Takes a Place ID or a Location and returns a list of users of your application who are within the bounding box of that Location.
Location Hash keys, in order of priority:
Not yet supported: