Asset API Adapter

The Asset API Adapter allows you to store assets -- resources or files of any kind -- used by a project with a scope that is specific to project, group, or end user.

Assets are used with team projects. One common use case is having end users in a group or in a multiplayer world upload data -- videos created during game play, profile pictures for customizing their experience, etc. -- as part of playing through the project.

Resources created using the Asset Adapter are scoped:

Project assets are writable only by team members, that is, Epicenter authors. Group assets are writable by anyone with access to the project that is part of that particular group. This includes all team members (Epicenter authors) and any end users who are members of the group -- both facilitators and standard end users. User assets are writable by the specific end user, and by the facilitator of the group. All assets are readable by anyone with the exact URI.

To use the Asset Adapter, instantiate it and then access the methods provided. Instantiating requires the account id (Team ID in the Epicenter user interface) and project id (Project ID). The group name is required for assets with a group scope, and the group name and userId are required for assets with a user scope. If not included, they are taken from the logged in user's session information if needed.

When creating an asset, you can pass in text (encoded data) to the create() call. Alternatively, you can make the create() call as part of an HTML form and pass in a file uploaded via the form.

// instantiate the Asset Adapter
var aa = new F.service.Asset({
   account: 'acme-simulations',
   project: 'supply-chain-game',
   group: 'team1',
   userId: '12345'
});

// create a new asset using encoded text
aa.create('test.txt', {
    encoding: 'BASE_64',
    data: 'VGhpcyBpcyBhIHRlc3QgZmlsZS4=',
    contentType: 'text/plain'
}, { scope: 'user' });

// alternatively, create a new asset using a file uploaded through a form
// this sample code goes with an html form that looks like this:
//
// <form id="upload-file">
//   <input id="file" type="file">
//   <input id="filename" type="text" value="myFile.txt">
//   <button type="submit">Upload myFile</button>
// </form>
//
$('#upload-file').on('submit', function (e) {
   e.preventDefault();
   var filename = $('#filename').val();
   var data = new FormData();
   var inputControl = $('#file')[0];
   data.append('file', inputControl.files[0], filename);
   aa.create(filename, data, { scope: 'user' });
});

Constructor options

Required?	Name	Type	Description
Yes	userId	string	The user id. Defaults to session's userId.
Yes	scope	user / group / project	The scope for the asset. Valid values are: user, group, and project. See above for the required permissions to write to each scope. Defaults to user, meaning the current end user or a facilitator in the end user's group can edit the asset.
Yes	fullUrl	boolean	Determines if a request to list the assets in a scope includes the complete URL for each asset (true), or only the file names of the assets (false). Defaults to true.
	account	string	The account id. In the Epicenter UI, this is the Team ID (for team projects) or User ID (for personal projects). Defaults to undefined. If left undefined, taken from the URL.
	project	string	The project id. Defaults to undefined. If left undefined, parsed from the URL.
	token	string	For projects that require authentication, pass in the user access token (defaults to undefined). If the user is already logged in to Epicenter, the user access token is already set in a cookie and automatically loaded from there. (See more background on access tokens). @see Authentication API Service for getting tokens.
	transport	JQueryAjaxOptions	Options to pass on to the underlying transport layer. All jquery.ajax options are supported.
	server	object
	server.host	string	The value of host is usually the string api.forio.com, the URI of the Forio API server. This is automatically set, but you can pass it explicitly if desired. It is most commonly used for clarity when you are hosting an Epicenter project on your own server
	server.protocol	https / http	Defaults to https

Methods

create(filename[, params, options])

Creates a file in the Asset API. The server returns an error (status code 409, conflict) if the file already exists, so check first with a list() or a get().

Parameters

Required?	Name	Type	Description
Yes	filename	string	Name of the file to create.
	params	object	Body parameters to send to the Asset API. Required if the options.transport.contentType is application/json, otherwise ignored.
	params.encoding	string	Either HEX or BASE_64. Required if options.transport.contentType is application/json.
	params.data	string	The encoded data for the file. Required if options.transport.contentType is application/json.
	params.contentType	string	The mime type of the file. Optional.
	options	object	Options object to override global options.

Example

var aa = new F.service.Asset({
         account: 'acme-simulations',
         project: 'supply-chain-game',
         group: 'team1',
         userId: ''
      });

      // create a new asset using encoded text
      aa.create('test.txt', {
          encoding: 'BASE_64',
          data: 'VGhpcyBpcyBhIHRlc3QgZmlsZS4=',
          contentType: 'text/plain'
      }, { scope: 'user' });

      // alternatively, create a new asset using a file uploaded through a form
      // this sample code goes with an html form that looks like this:
      //
      // <form id="upload-file">
      //   <input id="file" type="file">
      //   <input id="filename" type="text" value="myFile.txt">
      //   <button type="submit">Upload myFile</button>
      // </form>
      //
      $('#upload-file').on('submit', function (e) {
         e.preventDefault();
         var filename = $('#filename').val();
         var data = new FormData();
         var inputControl = $('#file')[0];
         data.append('file', inputControl.files[0], filename);

         aa.create(filename, data, { scope: 'user' });
      });

get(filename[, options])

Gets a file from the Asset API, fetching the asset content. (To get a list of the assets in a scope, use list().)

Parameters

Required?	Name	Type	Description
Yes	filename	string	(Required) Name of the file to retrieve.
	options	object	Options object to override global options.

list([options])

Gets the list of the assets in a scope.

Parameters

Required?	Name	Type	Description
	options	object	Options object to override global options.
	options.scope	string	The scope (user, group, project).
	options.fullUrl	boolean	Determines if the list of assets in a scope includes the complete URL for each asset (true), or only the file names of the assets (false).

Example

aa.list({ fullUrl: true }).then(function(fileList){
          console.log('array of files = ', fileList);
      });

replace(filename[, params, options])

Replaces an existing file in the Asset API.

Parameters

Required?	Name	Type	Description
Yes	filename	string	Name of the file being replaced.
	params	object	Body parameters to send to the Asset API. Required if the options.transport.contentType is application/json, otherwise ignored.
	params.encoding	string	Either HEX or BASE_64. Required if options.transport.contentType is application/json.
	params.data	string	The encoded data for the file. Required if options.transport.contentType is application/json.
	params.contentType	string	The mime type of the file. Optional.
	options	object	Options object to override global options.

Example

// replace an asset using encoded text
      aa.replace('test.txt', {
          encoding: 'BASE_64',
          data: 'VGhpcyBpcyBhIHNlY29uZCB0ZXN0IGZpbGUu',
          contentType: 'text/plain'
      }, { scope: 'user' });

      // alternatively, replace an asset using a file uploaded through a form
      // this sample code goes with an html form that looks like this:
      //
      // <form id="replace-file">
      //   <input id="file" type="file">
      //   <input id="replace-filename" type="text" value="myFile.txt">
      //   <button type="submit">Replace myFile</button>
      // </form>
      //
      $('#replace-file').on('submit', function (e) {
         e.preventDefault();
         var filename = $('#replace-filename').val();
         var data = new FormData();
         var inputControl = $('#file')[0];
         data.append('file', inputControl.files[0], filename);

         aa.replace(filename, data, { scope: 'user' });
      });

getTargetUploadURL(filename[, params, options])

Get upload url to S3. Useful if you're uploading large assets and would like to skip the middle-man (Epicenter) and upload to S3 directly.

Parameters

Required?	Name	Type	Description
Yes	filename	string	Name of the file to upload.
	params	object
Yes	params.ttlSeconds	number	Number of seconds link is valid for
	options	object	Options object to override service options.

delete(filename[, options])

Deletes a file from the Asset API.

Parameters

Required?	Name	Type	Description
Yes	filename	string	(Required) Name of the file to delete.
	options	object	Options object to override global options.

Example

aa.delete(sampleFileName);