Geni Applications

Geni Platform provides a mechanism for creating your own embedded applications (extensions) for the site. Geni extensions are applications that are launched inside of an iframe on the site.

This document provides you with steps for creating your own extension and embed it into the site.

Embedded Application Example

Below is an example of a Photo Gallery extension that loads user's photo albums and displays them using an interactive layout. The embedded application is running inside of an iFrame and is served by a server outside of Geni.

Embedded Application Registration

In order to create an embedded application, you have to provide the following information:

Application Fields

Name Description Required
Site URL URL where user will be taken to for full application functionality. false
Site Domain Used for security purposes. Application authorization will not succeed unless you provide your site domain. true
Application Type For a site extension, this field must be set to "Web". true
API Version Default API version to be used, unless it is provided in the API request. false
Callback URL Default callback URL (redirect_uri) that will be used for application authorization callback, unless it is provided in the parameters of the oauth request. false
Deauthorization Callback URL When user removes (deauthorizes) your application, we will call this URL with user information. true
Canvas Page Name of the canvas page that will be used to identify your application on Geni. This name must be unique and distinctively identify your application. true
Canvas URL URL of your application's main page. true
iFrame Size You have two options: limit application to the default 800x640 size of the iFrame and display scrollbars if your content is larger than the default size or make the application height grow with your content size. Choose "Auto-resize" if you are going to make the iFrame grow to the height of your app's content. true
Authorization Choose "App will handle authorization" if your application will handle the authorization. Otherwise we will make sure the user has authorized your application and will pass you an access token as a parameter. true

Authorization Flow

There are two ways you could authorize your embedded application. If you chose to let Geni handle authorization then we will check if the user has authorized your application, and if not, we will present the authorization screen. Once user has authorized your app, we will pass you a valid access token as a parameter to your apps canvas URL. Alternatively, you can take the userto the authorization flow yourself, by redirecting the iframce to the authorization URL.

Oauth URL

https://www.geni.com/platform/oauth/authorize

Parameters

Name Description Required
client_id Application key generated during the app registration. true
redirect_uri URL that the user's browser will be redirected back to once the application authorization is completed. You can specify this URL in your application settings as a Callback URL, or pass it as a request paremeter. The redirect_uri must be within the same domain as the Site Domain you specified in the application settings. true
response_type For the server side flow the response type is defaulted to "token" and you don't need to pass it as a parameter. true
scope A comma delimited list of permissions that the application needs. By default the scope is set to a full data access.This is subject to change in the upcoming releases. false
display For the server side flow the display parameter is defaulted to "web". false

Example

https://www.geni.com/platform/oauth/authorize?client_id=YOUR_APP_KEY&redirect_uri=YOUR_URL&response_type=token

If the user presses Don't Allow, your app is not authorized.The user will be redirected (via HTTP 302) to the URL you passed in the redirect_uri parameter with the following error information:

Returned Fields

Name Type Description
status String If user cancels the authorization flow, the status will be set to "unauthorized".
message String Error message

Example

http://YOUR_URL#status=unauthorized&message=user+canceled

If the user presses Allow, your app is authorized.The user will be redirected (via HTTP 302) to the URL you passed in the redirect_uri parameter with an authorization code:

Returned Fields

Name Type Description
access_token String Access token to be used with every API request
expires_in Number Seconds until the token will expire

Example

http://YOUR_URL#access_token=ACCESS_TOKEN_GENERATED_BY_SERVER&expires_in=SECONDS_UNTIL_IT_IS_EXPIRED
app005