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.
Create and Manage Applications
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
