User Content Overview

Note

Stability: 0 - Internal

The Hydra User Content service provides features for storage, publishing, rating, and ranking of arbitrary user content. Applications range from simple screenshot uploads to complex mods with multiple associated files ranked with a user scoring system. The upload portion of the service can be useful for backups, sharing, and cloud syncing.

All user content is private by default and can only be accessed by the user. The user content service supports sharing of both read and write access to individual items and versions with a set of white-listed user accounts. In this way, players can privately share with other users and collaborate with friends. When it comes time to share the content with the world, publishing through the user content service will allow users to add ratings and add the content to our public search indexes and leaderboards.

Future iterations will improve on published items with more robust searching, access control, collections, and comment/review support.

Item Types Overview

The first step to using the content service is configuring a set of item types using the Hydra developer dashboard. These types define both the structure of the content items as well as feature configuration for files, ratings, and leaderboards. In future releases, changes to an item type configuration may spawn offline processes to propagate those changes to affected user content. Currently, any changes to item type configuration will only affect future operations. Existing content will not be modified in any way.

  • Slug - The item type’s unique identifier (1-23 characters). Cannot be changed once set.
  • Name - Human friendly name to display in interfaces.
  • Description - Human friendly description to display in interfaces.
  • Use Versions - Check this box to take advantage of versions. If this box is not checked, all version specific actions can be taken on the item instead which manages a single version internally.
  • Metadata - Free-form json data that will be returned with this type when retrieved by any client.
  • File Attachments - Configure files that can be attached to items of this type. See File Attachments Configuration below.
  • User Ratings - Configure ratings that can be added to published items of this type. See User Ratings Configuration below.
  • Leaderboards - Configure leaderboards for published items of this type. See Leaderboard Configuration below.

File Attachments Configuration

Each item type has its own file upload configuration. By default, all file uploads to an item are forbidden. The item type must be configured to allow uploads by including one or more file types in its configuration.

  • Label - The file type’s unique (within each item type) identifier. Cannot be changed once set.
  • File Class - The class of file that is expected to be uploaded. See File Class Configuration below.
  • Max Size - The maximum size, in bytes, for any file uploaded under this label.
  • Min Count - The minimum number of files that should be uploaded under this label (per item version).
  • Max Count - The maximum number of files that can be uploaded under this label (per item version).
  • Options - Class specific file type options, see the file class configuration options below.

Uploads over the maximum size will be rejected. Min count and max count are currently unused but will be used for pre-publishing validation in future releases.

File Class Configuration

Files uploaded to items must fall under one of the classes of file below. In future releases, each class will have configuration options for content validation, storage, retrieval, and pre/post processing.

Available file classes:

  • Blob - Raw binary data. No current configuration available.
  • Image - Either PNG or JPEG data. See Image Class Configuration below.

Because each class of file has a separate set of associated options and properties ContentFileTypes and ContentFiles in the SDKs are always instantiated as a class specific implementation of the base ContentFileType and ContentFile classes. To access type specific properties or functionality recast files to the appropriate type using their FileClass property.

Image Class Configuration

You can request that all uploaded files of a given type have thumbnails automatically generated by Hydra. Thumbnails are generated such that the aspect ratio of the original image is preserved and the resulting image does not exceed the specified width and height dimensions.

  • Thumbnail - When true both the max width and height of the thumbnail must be added.
  • Width - The maximum allowable width for the thumbnail.
  • Height - The maximum allowable height for the thumbnail.

User Ratings Configuration

Ratings provide users the ability to provide feedback on user content that is automatically aggregated and made available in the main item body. Each item type has its own user ratings configuration. By default, all user ratings on items are forbidden. The item type must be configured to allow user ratings by including one or more rating types in its configuration.

  • Type Slug - The rating type’s unique (within each item type) identifier. Cannot be changed once set.
  • Type Class - The class of rating. Affects how each individual score is summarized and aggregated. See Rating Class Configuration below.

Each user can maintain a single rating per type per item. This rating tracks the item version it was applied to so that ratings can be marked out of date. Users can only rate items that have been published. In future versions we will also aggregate rating scores to individual versions of a user item.

Rating Class Configuration

Ratings added to items must fall under one of the rating classes below. The rating class and its configuration affect how user scores are aggregated to the target item. In future releases, the rating class and its configuration may also affect the options available during rating submission.

  • Percent - Provides the average rating score as a percentage of the possible total. See Percent Class Configuration below.
  • PlusMinus - Provides the net rating score as well as counts and totals in both the “plus” and “minus” directions. See PlusMinus Class Configuration below.
  • Histogram - Provides the average rating score as well as rating counts for each histogram bucket. See Histogram Class Configuration below.

Because each class of rating has a separate set of associated options and properties RatingFileTypes and RatingData objects in the SDKs are always instantiated as a class specific implementation of the base RatingFileType and RatingData classes. To access type specific properties or functionality recast ratings in the appropriate type using their TypeClass property.

Histogram Class Configuration

Histogram type ratings can be used to provide “5 Star” type ratings and provide basic information on score distribution. The following aggregations are provided:

  • Num Ratings - The total number of ratings of this type applied to this item.
  • Average Score - The average score from all of the ratings of this type applied to this item. Calculated as sum(scores)/num_ratings.
  • Buckets - An array of histogram buckets with per-bucket rating counts. * Lower Bound - The lowest score for this bucket. * Upper Bound - The highest score for this bucket. * Num Ratings - The total number of ratings in this score range.

Percent Class Configuration

Percent type ratings can be used to provide a X of Y type score system or provide percentage aggregations of boolean ratings. The following aggregations are provided:

  • Num Ratings - The total number of ratings of this type applied to this item.
  • Average Percent - The average percentage score from all of the ratings of this type applied to this item. Calculated as sum(scores)/(num_ratings * max_score).

PlusMinus Class Configuration

PlusMinus type ratings can be used to provide a Reddit or Facebook style rating system where the primary concern is the total aggregate score. The following aggregations are provided:

  • Num Ratings - The total number of ratings of this type applied to this item.
  • Num Plus Ratings - The total number of positive ratings of this type applied to this item.
  • Num Minus Ratings - The total number of negative ratings of this type applied to this item.
  • Total Score - The net aggregate score from all ratings of this type applied to this item.
  • Total Plus Score - The total score from all positive ratings of this type applied to this item.
  • Total Minus Score - The total score from all negative ratings of this type applied to this item.

Leaderboard Configuration

See Leaderboards for more information.

Schemas

Item Type Document:

{
    "id": "53ea3ffcd559926870d0df26",
    "slug": "testingitemtype",
    "name": "TestingItemType",
    "description": "",
    "use_versions": False,
    "file_types": [
        <file_type_doc>,
        <file_type_doc>,
    ],
    "rating_types": [
        <rating_type_doc>,
    ]
    "created_at": "2014-08-12T16:25:32+0000",
    "updated_at": "2014-08-12T16:25:32+0000"
}

File Type Document:

{
    "file_class": "image",
    "label": "basicimage",
    "min_count": 0,
    "max_count": 4,
    "max_size": 500000,
    "options": {
        // Options specific to the file class chosen above
        "thumbnail": True,
        "thumbnail_max_height": 120,
        "thumbnail_max_width": 100
    }
}

Rating Type Document:

{
    "type_class": "histogram",
    "type_slug": "histogram-rating-type",
    "min_score": 1,
    "max_score": 10,
    "bucket_size": 2,
}

Leaderboard Document

{
    "slug": "highest-rated-items",
    "name": "Highest Rated Items",
    "description": "The highest rated items this week",
    "tracked_stat": "ratings.histogram-rating-type.avg_score",
    "expiration": None,
}

Items Overview

Items are the basic containers of content and are always created with a associated item type that defines the behavior of the item, the files that can be attached to it, and how it interacts with other user content features. The primary purpose of items is to act as containers for versions, manage access control, and track version history.

If you don’t need versions, leave the use_versions option unchecked on the item’s type and we will internally create and manage a version for you. Items configured in this way have a simpler work flow and can have all version actions taken directly against the item instead. If the use_versions option is checked, then you are responsible for creating the initial version yourself and version actions should be taken directly against the version you want to affect. See the Versions Overview for more information.

Basic Item Fields:

  • Name - The item name.
  • Description - The item description.
  • Owner Id - The id of the user that created the item.
  • Type Slug - The slug of the item type for this item.
  • Shared - A flag marking the item as shared with other users.
  • Public - A flag marking the item as published for public access.
  • Data - A free form data field for your personal use.
  • Version - The current version of this item. See Versions Overview.
  • Access Control List - The access control configuration for this item. See Item Access Controls.
  • Ratings - The aggregated rating data for this item. See Item Ratings Data.

Versioned Item Fields (see Versions Overview):

  • Private Version - The most recent version of this item.
  • Private History - A chronological list of all versions of this item.
  • Shared Version - The most recent shared version of this item.
  • Shared History - A chronological list of all the shared versions of this item.
  • Public Version - The most recent published version of this item.
  • Public History - A chronological list of all the published versions of this item.

If a person has access to load an item, depending on who they are they will only see a subset of the item data. All users have full access to the name, description, owner id, type slug, shared, public, data, public version, public history and version fields. If the item has been shared with you the shared version and shared history fields are returned as well. Owners and administrator always have access to all data.

Important: This means that the item data fields should not be used to store private information for public or shared items. There is not currently a good place to put information intended to be private on shared or public items.

Item Access Controls

Access controls only apply to items/versions that are shared. Public items/versions bypass access controls and private items/versions are only accessible by owners and administrators. Read and write access are managed separately in access control as white lists.

  • Friends - Friends of the owner have access for this item.
  • Users - Users listed here have access for this item.
  • Clans - Members of the clans listed here have access for this item.

Important: Friend and clan based access control are not implemented in the current release.

When thinking about what becomes visible when a version is shared, it is helpful to think of the item as a container. When a version is shared, the item it belongs to must also become available to the people the version was shared with. Other shared versions will stay private but the item container always shares the access level of its most accessible version.

The same is currently true for write access to items as well. Any user with write access to any version of an item has write access to the parent item itself and can create new versions or delete old versions that they have access to. Only the item owner has permissions to publish/unpublish.

Important: Be cautious who you share write access with.

Item Publishing

When an item or version is published, both the version and the parent item become accessible to all users and the item is added to the item search index. Only the item owner has permissions to publish/unpublish. That item also gets added to all configured leaderboards and becomes a valid target for user ratings.

When thinking about what becomes visible when a version is published, it is helpful to think of the item as a container. When a version is published, the item it belongs to must also become publicly available. Other unpublished versions will stay private/shared but the item container always shares the access level of its most accessible version.

At this time there are no controls in place to prevent or limit the editing of published content.

Item Ratings Data

When ratings are configured for an item’s type it’s ratings data sub-document is populated with the configured rating type’s aggregations. As ratings are created for the item this summary data is updated in realtime to reflect the item’s new rating status. See the Rating Class Configuration for information about what aggregations are made available for each class of rating type.

New in 1.19.0 - This item ratings data is also aggregated to each of the item’s versions. These aggregates on each version reflect the item ratings that are currently targeting that version of the item to provide a more granular view of ratings data.

Item Schemas

Item Document:

{
    "name": <non-unique name>,
    "description": <short description>,
    "owner_id": <account_id>,
    "type_slug": <item type slug>,
    "shared": <bool>,
    "public": <bool>,
    "private_version": <version_id>,
    "private_history": [<version_id>, ...],
    "shared_version": <version_id>,
    "shared_history": [<version_id>, ...],
    "public_version": <version_id>,
    "public_history": [<version_id>, ...],
    "version": <version_doc>,
    "acl": <access_control_doc>,
    "ratings": <ratings_data_doc>,
    "data": {
        // Optional user metadata
    }
    "server_data": {
        // Optional server metadata
    }
}

Access Control Document:

{
    "read": {
        "friends" <bool>,
        "users": [<account_id>, ...],
        "clans": [<clan_id>, ...]
    },
    "write": {
        "friends" <bool>,
        "users": [<account_id>, ...],
        "clans": [<clan_id>, ...]
    }
}

Rating Data Document:

{
    "rating-type-slug": {
        // a subset of the following rating class aggregations
        "num_ratings": 10,
        "avg_score": 3,
        "total_score": 30,
        "avg_percent": .6,
        "num_plus_ratings": 10,
        "num_minus_ratings": 0,
        "total_plus_score": 30,
        "total_minus_score": 0
    },
    "rating-type-slug-2":{
        // a subset of the following rating class aggregations
        "num_ratings": 0,
        "avg_percent": 0
    }
}

Versions Overview

Versions are the basic unit of content and represent an instance of the parent item. Versions can be individually shared and published and act as a container for files that represent a state for the item.

  • Revision - Integer that increments with each new version of an item. It does not change if the version is later updated.
  • Shared - A flag marking the version as shared with other users.
  • Public - A flag marking the version as published for public access.
  • Parent - The id of the active version at the time this version was created.
  • Files - A list of files that have been attached to this item version.
  • Data - A free form data field for your personal use.

If a person has access to load a version, they will have access to load all version data.

Important: This means that the version data fields should not be used to store private information for public or shared versions. There is not currently a good place to put information intended to be private on shared or public versions.

Version Files

When you attach a file to an item/version a new entry for the file is added to the version. The data associated with that file then has to pass through the requirements imposed by the corresponding file type configuration and any pre-processing steps are performed. An attempt is then made to upload the data to the CDN after which any post-processing steps are performed.

  • UUID - A unique file identifier that is automatically assigned on creation
  • Name - The name of the file
  • Type Label - The label of the file type that this file should be added as.
  • File Class - The class of file data. Automatically assigned from the file type.
  • Size - The size in bytes of the data associated with the file
  • Uploaded - A flag marking a file’s content as successfully uploaded.
  • Mime Type - The mime type you want to associate with the file data.
  • Url - The url that can be used to retrieve the file data.

If there is a failure to upload to our CDN we will not store the data locally and retry. Instead we will mark the file as not uploaded and wait for you to resubmit the data with a file update. For this reason, it is very important to verify that your file data has been uploaded after submission.

File data is never returned with GET requests and must be retrieved separately from the CDN.

Version Schemas

Version Document:

{
    "item_id": <item_id>,
    "owner_id": <account_id>,
    "type_slug": <item_type_slug>,
    "revision": 1,
    "public": <bool>,
    "shared": <bool>,
    "parent": <version_id>,
    "files": [
        <file_doc>,
        <file_doc>,
    ],
    "data": {
        // Optional user metadata
    }
    "server_data": {
        // Optional server metadata
    }
}

File Document:

{
    "uuid": <unique file identifer>,
    "name": <used to name files during download>,
    "file_class": <the class of file represented>,
    "size": <the size of the file content in bytes>,
    "uploaded": <flag indicating content upload status>,
    "mime_type": <image/jpeg, etc>,
    "type_label": <label from the file type configuration of the item>,
    "url": <the url for file content retrieval>,

    // File class specific fields
    "thumbnail_size": 0,
    "thumbnail_uploaded": false,
    "thumbnail_url": null,
}

Item Ratings Overview

User ratings provide a simple mechanism for aggregating user feedback to specific items in a structured manner. This aggregation can be used to power leaderboards and provide feedback to item creators.

  • Item Id - The id of the item being rated
  • Version Id - The version of the item being rated
  • Owner Id - The owner of the item being rated
  • Author Id - The user that created the rating
  • Type Slug - The rating’s type’s slug.
  • Type Class - The rating’s class. One of ‘histogram’, ‘plusminus’, ‘percent’.
  • Score - The score assigned to the item, must be an integer.
  • Data - A free form metadata field for your personal use.

References to item and version ids are not maintained; versions and items can be deleted at any time and the ids in the ratings object may be invalid at access time.

Leaderboards Overview

Item Leaderboards provide realtime ranking of items of an item type on a pre-configured item field value.

See Leaderboards for more information.

Histories Overview

See Histories Documentation for details.

Reference Links:

Search Overview

See Search Documentation for more details.

Item Search is comprised of Search Configurations and Saved Searches, both of which are configured through the dashboard. When writing field paths, start from the item root. To index version fields use the version. prefix. Examples:

  • name - The item name
  • data.category - The item category
  • version.name - The version name
  • version.data.category - The version category
  • version.aggregates.example.count - The number of sources that have been aggregated
  • ratings.example.num_ratings - The number of ratings on this item

If you are using versions, only the most recent versions in each context (public, shared, private) will be searchable. For any given search, only the version of the item that matches the query context is searched against. In the default context the version preference is private, shared, public based on the access privileges of the querying user.

Reference Links:

  • Term Counts C++

Code Samples

Item Type Actions

Load Item Type

Item types can be loaded by either id or slug.

  • client->getUserContentService()->loadItemType(slug, [](apiframework::shared_ptr<UserContentItemType> itemType, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

List Item Types

  • client->getUserContentService()->LoadItemTypes(slug, [](std::vector< apiframework::shared_ptr<UserContentItemType> > itemTypes, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Item Actions

Create Item

Items can be created with default settings or with all settings pre-set using the following options:

  • Description - Set the item description.
  • Data - Set the item user data.
  • Access Control - Set access control settings for this item.
  • Shared - Set to true to share this item immediately. Only valid when versions are not used.
  • Public - Set to true to publish this item immediately. Only valid when versions are not used.
  • Map* dataMap = new Map();
    dataMap.set("field1", "value1");
    
    UserContentAccessControl* acl = new UserContentAccessControl();
    acl.read.users.push_back(accountId);
    acl.write.users.push_back(accountId);
    
    // With options
    UserContentItemCreateOptions options();
    options.setDescription(myDescription);
    options.setData(dataMap);
    options.setAccessControl(acl);
    options.setShared(True);
    options.setPublic(False);
    
    client->getUserContentService()->createItem(itemTypeSlug, itemName, options, [](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Load Item

When an item is loaded, a version is automatically loaded and returned in the version field. This version is automatically chosen to be the most recent version that the requester has access to. All accessible data for both the item and version will be returned.

To customize this behavior you have the following options available:

  • Version Id - Load a specific version that you know about already.
  • Context - Use to specify the most recent public or shared version for loading, regardless of personal access levels.
  • Fields - Use to restrict the item data fields to just the ones listed.
  • Version Fields - Use to restrict the version data fields to just the ones listed.
  • std::vector<std::string> fields;
    fields.push_back("data.field_to_load");
    
    std::vector<std::string> versionFields;
    versionFields.push_back("data.field_to_load");
    
    UserContentItemLoadOptions options;
    options.setFields(fields);
    options.setVersionId(versionToLoad);
    options.setVersionFields(versionFields);
    options.setContext(UserContentContext::Public);
    
    client->getUserContentService()->loadItem(itemId, options, [](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Update Item

An item can be either updated by a map of changes or by a set of commands. These data updates will be automatically applied to the item instance on request success.

  • Commands* updates = new Commands();
    updates->put("name", newName);
    updates.setValue("data.key", new String("value"));
    updates.incValue("data.score", new Integer(1));
    item->update(updates, [](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Delete Item

Deleting an item will also remove all linked versions and files.

  • client->getUserContentService()->deleteItem(itemId, [](Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Sharing

Sharing an item or version by itself does not let other people access/update it. You must also set appropriate access controls on the item.

  • item->share([](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
    item->shareVersion(versionId, [](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
    item->unshare([](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
    item->unshareVersion(versionId, [](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Publishing

Only an owner has permission to publish an item or version. Once published, the item will be indexed for searches and will be accessible to the public.

  • item->publish([](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
    item->publishVersion(versionId, [](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
    item->unpublish([](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
    item->unpublishVersion(versionId, [](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

List Items

When listing items, each loaded item also loads a version in the version field. This version is automatically chosen to be the most recent version that the requester has access to. By default, data and server_data information is excluded from all list commands.

To customize this behavior you have the following options available:

  • Page - The page of results you want.
  • Count - The number of item results per page.
  • Context - Use to specify the most recent public or shared version for loading, regardless of personal access levels.
  • Fields - Use to restrict the item data fields to just the ones listed.
  • Version Fields - Use to restrict the version data fields to just the ones listed.

When listing by owner you gain additional options:

  • Type Slug - Further filter item listing by the item’s type slug.
  • // List by type
    UserContentItemListByTypeOptions options();
    options.setPage(2);
    options.setCount(25);
    options.setContext(UserContentContext::Shared);
    client->getUserContentService()->loadItemsByType(slug, options, [](const PagedSharedPtrResult<UserContentItem>& items, Request* request) {
        // ...
    });
    
    // List by owner
    UserContentItemListByOwnerOptions options();
    options.setTypeSlug(itemTypeSlug);
    client->getUserContentService()->loadItemsByOwner(ownerId, options, [](const PagedSharedPtrResult<UserContentItem>& items, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Search Items

Search through published items/versions using a pre-configured query. See Search Query Configuration for details.

Options:

  • Limit - The maximum number of results to return in this result set
  • Cursor - The cursor to resume a previous search with. Each response will return a new cursor if there are additional results.
  • Request Params - A map of request parameters accepted by the search query.
  • Fields - The item user data fields to return with this result set.
  • Version Fields - The version user data fields to return with this result set.

NOTE: No more than 1000 results can be pulled back from a search query. It is not intended as a way of scanning the item database.

  • UserContentItemSearchOptions options();
    options.setLimit(20);
    options.setRequestParam("name", "zombie apocolypse");
    client->getUserContentService()->searchItems(itemTypeSlug, querySlug, options, [](const SearchSharedPtrResult<UserContentItem>& items, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Version Actions

Create Version

Versions can be created with default settings or with all settings pre-set using the following options:

  • Data - Set the version user data.
  • Shared - Set to true to share this version immediately. Collaborators automatically share versions they create.
  • Public - Set to true to publish this version immediately. Collaborators cannot publish versions.
  • item->createVersion(options, [](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Load Version

For when you want to change the loaded version of an item. An optional fields parameter lets you filter the data returned on the newly loaded version.

  • std::vector<std::string> fields;
    fields.push_back("data.field_to_return");
    
    item->loadVersion(versionId, fields, [](apiframework::shared_ptr<UserContentVersion> version, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Update Version

An version can be either updated by a map of changes or by a set of commands. These data updates will be automatically applied to the version instance on request success.

  • Commands updates;
    updates.setValue("data.key", new String("value"));
    updates.incValue("data.score", new Integer(1));
    version->update(updates, [](apiframework::shared_ptr<UserContentVersion> version, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Delete Version

Deleting a version will remove all corresponding file content and reset the item to the previous version. If this was the only published or shared version of the item it will cause the item to automatically become unpublished or unshared.

  • item->deleteVersion(versionId, [](apiframework::shared_ptr<UserContentItem> item, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Load Versions

To load all the versions of an item you must use the UserContentService directly. The following options are available:

  • Page - The page of versions you want.
  • Count - The number of versions per page.
  • Context - Use to restrict to only versions that are shared or versions that are public.
  • Fields - Use to restrict the item data fields to just the ones listed.
  • std::vector<std::string> fields;
    fields.push_back("data.field_to_load");
    
    UserContentVersionListOptions options;
    options.setPage(1);
    options.setCount(25);
    options.setContext(UserContentContext::Shared);
    options.setFields(fields);
    
    client->getUserContentService().loadVersions(itemId, options, [](PagedSharedPtrResult<UserContentVersion>& versions, Request* request) {
        // ...
    }
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

File Actions

Create File

New files are automatically added to the versions instance’s files list. The response must be checked for uploaded=True to verify that the content was successfully uploaded. For image files that have thumbnails generated, you should also verify that thumbnail_uploaded is true. False uploaded values indicate that the upload failed and you must use a file update to resend the content.

  • Type Label - The label of the file type to upload as.
  • Name - The file name. Appended to the end of the url for downloads. Defaults to the file’s auto-generated uuid.
  • Mime Type - The file mime type. Set on the CDN to identify downloads. Defaults to ‘application/octet-stream’
  • Content - The binary contents of the file.

To defer content upload you can create without file content and upload contents in a separate update statement at a later point.

  • Binary content(...);
    
    UserContentFileCreateOptions options;
    options.setName(fileName);
    options.setMimeType(mimeType);
    options.setContent(&content);
    
    version->createFile(typeLabel, options, [](apiframework::shared_ptr<UserContentFile> file, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Update File

Any updated file fields you send will be replaced in full. Content updates will first remove the old content, then process the new content as it would during file creation. As with file creation, check the uploaded flags to verify that your content was successfully uploaded. Fields available for update:

  • Name - Replaces the file name
  • Mime Type - Replaces the file mime_type
  • Content - Replaces the file content.

Note: If you don’t submit new content, any name or mime-type changes will not be reflected on the CDN.

  • Binary updateContent(...);
    
    UserContentFileUpdateOptions options;
    options.setName("Updated Name");
    options.setMimeType("new/mimeType");
    options.setContent(&updatedContent);
    
    version->updateFile(fileUUID, options, [](apiframework::shared_ptr<UserContentFile> file, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Delete File

Removed files are automatically removed from the version instance’s files list.

  • version->deleteFile(fileUUID, [](Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Item Rating Actions

Create Rating

Creates a new rating for the given item with the currently authenticated user. Only one rating of each type per item per user is permitted. Options available for rating creation:

  • VersionId - Defaults to the current published version of the item, NOT the currently loaded version of the item.
  • Data - Free form user metadata to attach to the item rating.
  • UserContentRatingCreateOptions options;
    options.setData(metadata);
    options.setVersionId(versionId)
    item->createRating(ratingTypeSlug, 10, options, [](apiframework::shared_ptr<UserContentItemRating> rating, Request* request) {
    
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Load Rating

Loads an item rating for the given user.

  • item->loadMyRating(ratingTypeSlug, [](apiframework::shared_ptr<UserContentItemRating> rating, Request* request) {
        // ...
    });
    
    apiframework::vector<apiframework::string> fields;
    fields.push_back("data.key");
    
    item->loadMyRating(ratingTypeSlug, fields, [](apiframework::shared_ptr<UserContentItemRating> rating, Request* request) {
        // ...
    });
    
    item->loadRating(ratingTypeSlug, authorId, [](apiframework::shared_ptr<UserContentItemRating> rating, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Update Rating

An rating can be either updated by a map of changes or by a set of commands. These data updates will be automatically applied to the rating instance on request success. Any updates to rating score will automatically be propagated to the affected item and leaderboards. Every update to the rating will update the version_id to the current published version unless version_id is manually set in the update.

  • Commands* updates = new Commands();
    updates.setValue("score", 8);
    updates.setValue("version_id", rating->getVersionId());
    updates.setValue("data.key", new String("value"));
    updates.incValue("data.score", new Integer(1));
    rating->update(updates, [](apiframework::shared_ptr<UserContentItemRating> rating, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Delete Rating

Removes the current user’s rating from the item. Automatically updates item aggregates and leaderboards.

  • item->deleteRating(ratingTypeSlug, [](Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

List Ratings for an Item

Returns a list of author ratings in chronological order of creation. Setting an optional versionId will restrict this query to ratings that are currently targeting the given version of the item.

  • apiframework::vector<apiframework::string> fields;
    fields.push_back("data.key");
    
    UserContentItemRatingListOptions options;
    options.setPage(10);
    options.setCount(25);
    options.setFields(fields);
    
    item->loadRatings(ratingTypeSlug, [](PagedSharedPtrResult<UserContentItemRating> ratings, Request* request) {
        // ...
    })
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

List Ratings by an Author

Returns a list of author ratings in chronological order of creation.

  • apiframework::vector<apiframework::string> fields;
    fields.push_back("data.key");
    
    UserContentItemRatingListOptions options;
    options.setPage(10);
    options.setCount(25);
    options.setFields(fields);
    
    client->getUserContentService()->loadMyItemRatings(itemTypeSlug, ratingTypeSlug, options, [](PagedSharedPtrResult<UserContentItemRating> ratings, Request* request) {
        // ....
    });
    
    client->getUserContentService()->loadItemRatingsByAuthor(itemTypeSlug, authorId, ratingTypeSlug, options, [](PagedSharedPtrResult<UserContentItemRating> ratings, Request* request) {
        // ....
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Item Leaderboard Actions

Load Item Leaderboards

Loads all of the leaderboard definitions for a given item.

  • apiframework::vector<apiframework::string> fields;
    fields.push_back("data.key");
    
    client->getUserContentService()->loadItemLeaderboards(itemTypeSlug, [](const apiframework::vector< apiframework::shared_ptr<UserContentItemLeaderboard> >& leaderboards, Request* request) {
        // ...
    });
    
    client->getUserContentService()->loadItemLeaderboards(itemTypeSlug, fields, [](const apiframework::vector< apiframework::shared_ptr<UserContentItemLeaderboard> >& leaderboards, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Load Item Leaderboard

Loads a specific leaderboard definition.

  • apiframework::vector<apiframework::string> fields;
    fields.push_back("data.key");
    
    client->getUserContentService()->loadItemLeaderboard(itemTypeSlug, leaderboardId, [](apiframework::shared_ptr<UserContentItemLeaderboard> leaderboard, Request* request) {
        // ...
    });
    
    client->getUserContentService()->loadItemLeaderboard(itemTypeSlug, leaderboardId, fields, [](apiframework::shared_ptr<UserContentItemLeaderboard> leaderboard, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Show Item Leaderboard Entries Paged

Returns a paged list of leaderboard entries ordered by rank where each entry has the following structure:

  • Rank - Leaderboard Rank
  • Score - Current score on the leaderboard
  • Item - Embedded Item Document (see Item Schemas). The contents of this item document can be restricted with the fields and version_fields`` options.

Accepts the following options:

  • Page - The page to return.
  • Count - The number of entries per page.
  • Order - The order to sort entries by. Does not affect rank, only the order of results returned. One of asc, desc. Defaults to desc.
  • History - For rotating leaderboards only. The default, 0, uses the current leaderboard. 1 uses the previous leaderboard, etc.
  • Fields - Fields parameter that is applied to the ranked item.
  • Version Fields - Fields parameter that is applied to the version loaded with the item (always the most recent public version).
  • apiframework::vector<apiframework::string> itemFields;
    apiframework::vector<apiframework::string> versionFields;
    
    UserContentItemLeaderboardOptions options;
    options.setPage(1);
    options.setCount(25);
    options.setHistory(1);
    options.setFields(itemFields);
    options.setVersionFields(versionFields);
    
    client->getUserContentService()->showItemLeaderboard(itemTypeSlug, leaderboardId, options, [](PagedSharedPtrResult<UserContentItemLeaderboardEntry> results, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Show Item Leaderboard Around Item

Returns a list of leaderboard entries around the specified item (50% before, 50% after) where each entry has the following structure:

  • Rank - Leaderboard Rank
  • Score - Current score on the leaderboard
  • Item - Embedded Item Document (see Item Schemas). The contents of this item document can be restricted with the fields and version_fields`` options.

Accepts the following options:

  • Order - The order to sort entries by. Does not affect rank, only the order of results returned. One of asc, desc. Defaults to desc.
  • History - For rotating leaderboards only. The default, 0, uses the current leaderboard. 1 uses the previous leaderboard, etc.
  • Fields - Fields parameter that is applied to the ranked item.
  • Version Fields - Fields parameter that is applied to the version loaded with the item (always the most recent public version).
  • apiframework::vector<apiframework::string> itemFields;
    apiframework::vector<apiframework::string> versionFields;
    
    UserContentItemLeaderboardOptions options;
    options.setHistory(1);
    options.setFields(itemFields);
    options.setVersionFields(versionFields);
    
    client->getUserContentService()->showItemLeaderboardAround(itemTypeSlug, leaderboardId, itemId, options, [](PagedSharedPtrResult<UserContentItemLeaderboardEntry> results, Request* request) {
        // ...
    });
    
  • Coming soon.
  • Not supported.
  • Coming soon.
  • Documentation coming soon.

Table Of Contents

Previous topic

Profile Feeds

Next topic

Generic Object Service