UGC API Setup

Follow

Javascript API

The following files are required for the JavaScript client-server API.  These files are included in the Agility UGC sample site.

Base Files

All of these files are available from Developer Downloads within Agility CMS Settings.

File  Description 
Agility.js Base reusable application functions.
Agility.UGC.API.js The main API for Agility UGC.
jquery-version.js Used for making AJAX requests, DOM manipulation, traversing etc.
   
AgilityRedirector.htm This file must be in the root of the application and is used as a location to redirect iframes used in cross-domain posts.

 

Initialize the Framework using .NET

Before any calls to the UGC API can be made, you must add the following initialization script to the page in your main razor layout. The helper method Agility.UGC.API.WCF.UGCAPIUtil.GetDataServiceInitializationScript will automatically generate the JavaScript initialization variables for you.

<script type="text/javascript">
@Html.Raw(Agility.UGC.API.WCF.UGCAPIUtil.GetDataServiceInitializationScript(-1))
</script>

 

Javascript Initialization Parameters

These are the parameters used to initialize the JS UGC framework. If you are using the helper method mentioned previously, you can ignore these.

Variable  Description 
Agility_BaseUrl  This is the path to the root of the application.  For a website, this will simply be “/”.  For a virtual folder, it would be “/virtualpath/”

Agility.UGC.API.OnInit(APIUrl, APIAccessKey, Seconds, RandomNumber, ProfileID, AccessHash)

This is the initialization call for the UGC API, and these values need to be calculated on the server and combined into a hash.  This is how the UGC server authorizes each request.  This method must be invoked before any other UGC call is invoked.

APIUrl is the absolute url to the JSONP handler on the UGC server.  This is unique for each Agility UGC site and will be provided for you.  If you have lost this URL, please email support@agilitycms.com.

The APIAccessKey is a GUID that identifies your application.  This will be provided for you.   If you have lost this key, please email support@agilitycms.com

Seconds is the number of seconds that have elapsed since Jan 1/2001.

RandomNumber is a random integer between 1 and 1000

ProfileID is the record ID of the website user who is currently logged into the system.  

  • This allows any records saved or requested by the system to be done on behalf of the authenticated user.  
  • If the user is not authenticated, use -1 for this.

AccessHash

  • This is an SHA hash of all of the above variables, plus the SecretKey for the application, which will be provided for you.
  • The variables are appended together and separated with periods before being hashed using SHA1:
    • Seconds.ProfileID.SecretKey.AccessKey.Random

 

Callbacks

The JavaScript API uses a callback paradigm with a generic Response object that has a success/failure flag with it. All of the functions, objects and enums in the Agility UGC API for JavaScript are in the Agility.UGC.API namespace.

This callback function has an object of the following structure:

Variable Description

ResponseType

Enum of type Agility.UGC.API.ResponseType

  • OK: 0
  • Error: 1

Message

A string value that is only populated if the ResponseType is Error.

ResponseData

The returned data object.

 

Server-Server API

There is one assembly and some web.config settings required for the Server-Server UGC API to run. 

Please note that we HIGHLY recommend accessing UGC only through the Javascript API.

Agility.UGC.API.WCF.dll

This is the main assembly that holds the proxy class and the utility class for WCF access to the UGC API.  The WCF proxy client no longer requires any settings in the web.config in order to work.  There is a new Utility class that will create the WCF Proxy for you as follows:

using (var client = Agility.UGC.API.WCF.UGCAPIUtil.APIClient)
{
    var dsa = UGCAPIUtil.GetDataServiceAuthorization(-1);
    //TODO: build search arg obj
    var results = client.SearchRecords(dsa, searchArg);
)

The only setting that will need to be set initially are the following appSettings in your web.config:

  • Agility_API_Key - the API Key provided for you.
  • Agility_API_Password - API Password provided for you.

Agility_UGC_API_WCFClient

Each server-to-server method in the UGC API is invoked using the Agility_UGC_API_WCFClient class, which is a WCF proxy class providing access to all of the methods in the API. It can be accessed through the static APIClient property of the UGCAPIUtil class.

DataServiceAuthorization

This DataServiceAuthorization object is obtained by using the UGCAPIUtil class in the Agility.UGC.API.WCF namespace. The method is GetDataServiceAuthorization and it takes an integer parameter which represents the current user in the context of the given request. If the user is not logged in, use -1 and the call will operate under the context of the system. If the user is logged in, use the ID of the record object that represents their profile. It is best to store this value in an encrypted cookie or the FormsAuthenticationToken.

Downloads

Download the latest release of the WCF DLL from Agility > Settings > Development Framework or from nuget

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.