top |
As the clients evolved terminology diverged from the backend database (or sometimes, the backend is a little more generic). Here is a list of equivalent objects in the system.
Backend | Client | ||
---|---|---|---|
User | Account | ||
Collection | Channel | ||
ContentFile | Video | ||
Post | Comment |
Users own (or follow, or contribute to) Collections. Collections have ContentFiles. ContentFiles have Posts. Posts have Posts (but only one level deep).
If an error occurs this is generally returned inside an error node:Note: most Error nodes contain a code attribute... but, so far, this usually is 0.
top |
Create a new SessionGuid (and return some additional system info.) This is effectively the login for the EQ Network API. UserName is the unique user (or account) name.
Xml Response:
SessionGuid is the value generated that you will use for all commands associated with this user.
The User node contains all of the User attributes.
ExpiredVersion, InvitationCount, NotificationCount and Following are all misc. pieces of system information that are useful
to have available when the user logs in (and creates a session.)
Check that a session is still valid. And, retrieves system information. SessionGuid identifies the session to check.
Xml Response:
InvitationCount and NotificationCount are misc. pieces of system information.
Note: If the session has expired an error would be returned.
TODO: Return everything a Session_Create does
top |
User_Create.aspx allows a user to be created. User_Update.aspx allows user attributes to be changed. User_Delete.aspx will delete a user. User_ListCollections.aspx will list a users collections. User_Search.aspx will search users. User_ListUsers.aspx will list a users relationships with other users. User_AddRelationship.aspx will create a relationship between two users. User_GetNode.aspx will retrieve a User node with user attributes.
In Xml Responses you may get one (or a list of) User nodes. A User node is a mix of user attributes and calculated user values. It will look like this:
UnviewedCount is sum of the Collections UnviewedCount being followed by this user.
UserTitle is a calculated value and will be Company, if it exists, or UserName. Use this value
to display the user as in the future we may change how a user is displayed on the backend, and then this would
propogate to all the clients.
UserId is a unique identifier of a User.
Active is True if the user is active, or false if the user has been deleted (but not yet scrubbed from
the database.)
Created is the date and time the User record was created.
Modified is the date and time the User record was last modified.
UserName,
Company,
FirstName,
LastName,
Email,
DateOfBirth,
Gender,
Phone and
Carrier
are all basic attributes of the user.
UserTypeId currently there is only one type of user (1: Normal).
IconFilename this is the filename of the users icon. See User Icon Url for more information on how to retrieve this image.)
Verified indicates if the user has been verified by their confirmation email.
ConfirmationGuid used to match a confirmation email with a user.
AgreementAccepted is the version level of the agreement the user has accepted.
Create a new user. This will also send a confirmation email if successfull. UserName is the unique user (or account) name.
Xml Response:
If you are returned a UserId, the user was created successfully.
Update user attributes. This will send a confirmation email if the email address has changed. SessionGuid identifies the user whose attributes will be updated.
(The descriptions for most other parameters can be found in User_Create.aspx.)
If Icon data does not exist then DeleteIcon will indicate wether, or not, this is because it has been deleted.
Note: all parameters must be present or they will be cleared out (except for Icon as noted).
Xml Response:
If you are returned an Ok, the user attributes were updated successfully.
Delete a user. SessionGuid identifies the user to delete.
Xml Response:
If you are returned Ok, the user was successfully deleted.
List Collections associated with a User. Pagination is supported. Search criteria is supported. SessionGuid identifies the user to list collections for.
Xml Response:
AsOfDate see AsOfDate behaviour
InvitationCount, NotificationCount and Following are all misc. pieces of system information (these are values global to the user.)
Collections is an array of Collection nodes (see Collection Nodes.)
Search Users. Pagination is supported. Search criteria is supported. SessionGuid identifies the user who is creating this relationship.
Xml Response:
Users is an array of User nodes (see User Nodes.)
List Users associated with a User. Pagination is supported. Search criteria is supported. SessionGuid identifies the user to list users for.
Xml Response:
Users is an array of User nodes (see User Nodes.)
Add a Relationship from one user to another. SessionGuid identifies the user who is creating this relationship.
Xml Response:
If you are returned an Ok, the relationship was updated successfully.
Retrieve the User node for a user. SessionGuid identifies the user to retrieve.
Xml Response:
(see User Nodes for User node information.)
top |
Collection_Create.aspx allows a collection to be created. Collection_Update.aspx allows collection attributes to be changed. Collection_Delete.aspx will delete a collection. Collection_AddRelationship.aspx will delete a collection. Collection_ListContentFiles.aspx will list a collections ContentFiles. Collection_GetNode.aspx will retrieve a Collection node with collection attributes.
In Xml Responses you may get one (or a list of) Collection nodes. A Collection node is a mix of collection attributes and calculated collection values. It will look like this:
RowNum is the ordered row number of the list of Collections when the request ultilizes pagination (see Pagination.)
ContentFileCount is the number of ContentFiles in this Collection.
UnviewedCount is the number of ContentFiles that have not been viewed.
MostRecent is the date/time of when the Collection was last viewed.
NotificationCount is the number of ContentFiles that have been added since this Collection was last viewed.
CollectionId is a unique identifier for the collection.
Active is True if the collection is active, or false if the collection has been deleted (but not yet scrubbed from
the database.)
Created is the date and time the Collection record was created.
Modified is the date and time the Collection record was last modified.
SortBy a custom sorting sequence for a list of Collections (not implemented).
Name is the name of the collection
Description is the description of the collection.
IconFilename this is the filename of the collections icon. See Collection Icon Url for more information on how to retrieve this image.)
CollectionTypeId is the collection type (1: Normal, 2:Private)
ViewCount is a count of how many times movies inside the collection have been viewed.
Categories is a comma delimited list of Categories (e.g. Sports, Golf)
NumberOfComments is a count of all the comments in this collection.
UserId is the unique identifier of the user this collection belongs to.
OwnerUserTitle is the UserTitle of the user this collection belongs to.
OwnerUserIconFilename is the IconFilename of the user this collection belongs to.
OwnerUserId is the UserId this collection belongs to.
User_CollectionTypeId defines the relationship between the user and the collection (1: Owner, 2: Follower, 3:Contributor).
Note: A Collection can have only one Owner. A Collection can have multiple Followers and/or Contributors. A Follower will receive notifications about changes in a Collection and the Collection will appear in the Followers Watch list. A Contributor is like a Follower, but additionally can add ContentFiles to this Collection.
Create a new collection. SessionGuid identifies the user that this collection will be added to.
Xml Response:
If you are returned a CollectionId, the collection was created successfully.
Update collection attributes. SessionGuid identifies the user whose collection attributes will be updated. This User must be the owner of the collection.
(The descriptions for most other parameters can be found in Collection_Create.aspx.)
If Icon data does not exist then DeleteIcon will indicate wether, or not, this is because it has been deleted.
Note: all parameters must be present or they will be cleared out (except for Icon as noted).
Xml Response:
If you are returned an Ok, the collection attributes were updated successfully.
The action taken with this command depends on the relation between the User and the Collection. If the User is the owner of this collection, then the collection will be deleted. If the User is a follower of, or contributor to, this collection... then this relationship will be deleted. SessionGuid identifies the User whose Collection (or collection relationship) is to be deleted.
Xml Response:
If you are returned Ok, the collection (or collection relationship) was successfully deleted.
This will add a "Following", or a "Contributor" relationship between a User and a Collection. SessionGuid identifies the User who will add a relationship to this collection.
Xml Response:
If you are returned Ok, the collection (or collection relationship) was successfully added.
Note: To remove this relationship, call Collection_Delete.asxp.
List ContentFiles associated with a Collection. Pagination is supported. Search criteria is supported only in the sense that the content files that match the search criteria get sorted first. SessionGuid identifies the user.
Xml Response:
AsOfDate see AsOfDate behaviour
ContentFiles is an array of ContentFile nodes (see ContentFile Nodes.)
Retrieve the Collection node for a collection. If the collection is private, then the user must be the owner of, a contributor to, or a follower of, the collection. SessionGuid identifies the user making the request (needed, for example, to ensure only valid users can access a private channel).
Xml Response:
(see Collection Nodes for Collection node information.)
top |
ContentFile_Create.aspx will upload and create a content file. ContentFile_CreateFromUrl.aspx will create a content file from a url provided. ContentFile_Update.aspx allows content file attributes to be changed. ContentFile_Delete.aspx will delete a content file. ContentFile_ListPosts.aspx will list a content files posts (or comments). ContentFile_GetNode.aspx will retrieve a ContentfIle node with content file attributes.
In Xml Responses you may get one (or a list of) ContentFile nodes. A ContentFile node is a mix of content file attributes and calculated content file values. It will look like this:
RowNum is the ordered row number of the list of ContentFiles when the request ultilizes pagination (see Pagination.)
ContentFileId is a unique identifier for the content file.
Active is True if the content file is active, or false if the content file has been deleted (but not yet scrubbed from
the database.)
Created is the date and time the ContentFile record was created.
Modified is the date and time the ContentFile record was last modified.
UserId is the unique identifier of the user this content file belongs to.
Name is the name of the content file
Description is the description of the content file.
Keywords are the keywords for this content file.
ContentFileTypeId is the content file type (1: Movie)
Filename is the filename of the content file. (this can uniquely identify the ContentFile, without providing a sequential index, for example in sharing.
DeliveryRequestId,
JdiResult and
MuxKey contains information about the downloading and/or processing of the video. (see DeliveryRequestId's and MuxKey's for more information).
IsAdult a flag that is True if an adult category was chosen for this content file (or containing collection).
Categories is a comma delimited list of Categories (e.g. Sports, Golf).
ViewCount is the number of times this content file has been viewed.
OriginalUrl is the url of where this files was downloaded from (if it was downloaded).
OriginalFilesize is the size of the original file.
DownloadUrl this may be different from the OriginalUrl if the movie was inside a page pointed to by OriginalUrl.
CollectionId the Collection this ContentFile belongs to.
UserViewCount the number of times this ContentFile has been viewed by the user making this request. (SessionGuid)
NumberOfComments the number of posts (and sub-posts) that have been made on this ContentFile.
SearchMatched indicates if this ContentFile matched a filter set (you still get the ContentFile... just, typically, ordered by Filter matches first).
CurrentTime in the case of a movie, this shows the time offset in the movie the user last viewed.
Note: A ContentFile can belong to only one collection.
Create a new content file. SessionGuid identifies the user who is adding this content file.
ButtonData
The JSON data is basically a bunch of key-value pairs of CSS. This allows nearly anything as far as designing the button.
The JSON object is subdivided into 2 separate objects – one from the container DIV, and the other for the anchor tag.
At the top level of the object, everything is proprietary and there is no CSS that can be specified:
appearTime: How many seconds of the video must elapse before the button appears. Leaving this off or setting it to 0 will cause the button to never appear.
disappearTime: How many seconds the button will stay visible. If left off or set to 0, and the button was made to appear, it will never disappear.
container: First subobject whose fields correspond to the CSS to assign to the container DIV. Use any CSS you like.
link: Second subobject whose fields correspond to the anchor tag that provides the link. It support a few proprietary tags in addition to any CSS:
text: The button text.
url: The URL to where the button links to. This link opens in a new browser tab.
Here is an example JSON string:
{ "appearTime": 1.0, "disappearTime": 10.0, "container": { "background-color": "#000080", "border": "2px solid white", "border-radius": "12px", "left": "100px", "top": "100px" }, "link": { "text": "Google", "url": "https://google.com", "font-size": "24px", "color": "yellow", "font-family": "Arial,Helvetica,sans-serif" } }
If you wish to have a button that is visible even before the video starts playing, you should leave off the appearTime field (or set it to 0) and insert some CSS into the DIV container subobject that makes it visible, i.e.: “display”: “inline-block”. By default the container DIV is set to display: none by the HTML on the embedded player page.
Xml Response:
If you are returned a ContentFileId, the content file was created successfully.
MuxKey contains information about the downloading and/or processing of the video. (see DeliveryRequestId's and MuxKey's for more information).
Create a new content file from a Url. The Url can be either a direct link to a movie file... or, a url to a page that contains flash video. SessionGuid identifies the user who is adding this content file.
(The descriptions for most other parameters can be found in ContentFile_Create.aspx.)
Url is an http link to either a file, or a page containing a flash movie.
IsFlashVideo is a flag indicating which type of Url it is (file or page containing flash).
Xml Response:
If you are returned a ContentFileId, the content file was created successfully.
MuxKey contains information about the downloading and/or processing of the video. (see DeliveryRequestId's and MuxKey's for more information).
top |
(The descriptions for most other parameters can be found in ContentFile_Create.aspx.)
If Video data does not exist then the video will remain the same.
Note: all parameters must be present or they will be cleared out (except for Video as noted).
Xml Response:
If you are returned a ContentFileId, the content file was updated successfully.
If video data was included MuxKey contains information about the downloading and/or processing of the video. (see DeliveryRequestId's and MuxKey's for more information).
This will delete a ContentFile. SessionGuid identifies the User whose ContentFile (or content file relationship) is to be deleted.
Xml Response:
If you are returned Ok, the content file (or content file relationship) was successfully deleted.
List Posts associated with a ContentFile. Pagination is supported. Filename identifies the ContentFile to list posts for.
Xml Response:
Posts is an array of Post nodes (see Post Nodes.)
In a post, Level is the depth of the post. There are two levels of depth. A depth of one for comments on the content file. And a depth of two for comments on a comment.
Retrieve the ContentFile node for a content file. If the collection this content file belongs to is private, then the user must be the owner of, a contributor to, or a follower of, the collection. SessionGuid identifies the user making the request (needed, for example, to ensure only valid users can access a private channel).
Xml Response:
(see ContentFile Nodes for ContentFile node information.)
top |
Post_Create.aspx will upload and create a post. Post_Delete.aspx will delete a post.
In Xml Responses you may get one (or a list of) Post nodes. A Post node is mix of post attributes and calculated post values. It will look like this:
RowNum is the ordered row number of the list of Posts when the request ultilizes pagination (see Pagination.)
Level is the depth of the post. There are two levels of depth. A depth of one for comments on the content file. And a depth of two for comments on a comment.
UserTitle is a calculated value and will be Company, if it exists, or UserName. Use this value
UserName is the UserName of the User who made this post
PostId is a unique identifier for the post.
Child_PostId the post unique identifier that this is a reply to.
UserId is the unique identifier of the user who made this post.
Title is the title of a comment (not currently used).
Message this is the body of the post.
Created is the date and time the Post record was created.
Create a new post. SessionGuid identifies the user who is adding this post.
Xml Response:
If you are returned a PostId, the post was created successfully.
This will delete a Post. SessionGuid identifies the User whose Post (or post relationship) is to be deleted.
Xml Response:
If you are returned Ok, the post was successfully deleted.
top |
Category_ListAll.aspx lists all valid categories.
In Xml Responses you may get one (or a list of) Category nodes. A Category node contains the category attribute values. It will look like this:
CategoryId is a unique identifier for the category.
Active indicates if the category is still in use.
Created is the date and time the Category record was created.
Modified is the date and time the Category record was last modified.
SortBy this is a float value that may modify the normal alphabetical display order (not currently used).
Name is the name of a category.
Message this is a description of a category (not currently used).
CategoryTypeId is the category type (1: Normal, 2:Adult)
Returns a list of all valid categories.
Xml Response:
top |
As a general overview on searching, typically several searches are performed. A search is performed on all content files (Search_ContentFiles.aspx), this gives you results that show up in the "top row". Additionally a search is performed on the collections and content files (Search_CollectionsAndContentFiles.aspx). This is used to retrieve a list of collection that match (or whose content files match) the search criteria.
Then, when one of these collections is viewed, the content files in that collection are retrieved by listing the content files (Collection_ListContentFiles.aspx), specifying the search criteria. This will cause *all* content files for that collection to be returned, but the ones that match the search criteria are at the front of the list.
The following are the major Search functions.
Search_ContentFiles.aspx will search content files. Search_CollectionsAndContentFiles.aspx will search collections and their content files.
Other functions that utilize search criteria parameters are:
User_ListCollections.aspx will list a users collections. User_ListUsers.aspx will list a users relationships with other users. Collection_ListContentFiles.aspx will list a collections ContentFiles.
The following are the parameters that make up the "search criteria" in a request.
Search is a search term that will match the names, descriptions, and categories of an item.
Categories will filter based on a comma delimited list of Categories (e.g. Sports, Golf).
HasPrefix will filter the results by the first letter of the items name (e.g. A, B, C) will limit the list to items whose name starts with the letter A, B, or C).
IncludeAdult filter to include content flagged as adult.
Search content files for matches to the search criteria. Search, Categories, HasPrefix and IncludeAdult are the search criteria. (see Search Criteria.)
Xml Response:
ContentFiles is an array of ContentFile nodes that match the search criteria (see ContentFile Nodes.)
Search collections (and their content files) for matches to the search criteria. Search, Categories, HasPrefix and IncludeAdult are the search criteria. (see Search Criteria.)
Xml Response:
Collections is an array of Collection nodes that match the search criteria (see Collection Nodes.)
Note: the search criteria is also applied to ContentFiles inside a Collection.
top |
A MuxKey contains information on the processing status and the playback versions of a movie file that are available. Currently the four playback versions are 3G, WiFi, WebM, and 720p. Each playback version is associated with a "DeliveryRequestId". An example of a MuxKey is:
M2960,13466~3G~3,13467~WiFi~3,13468~WebM~3,13469~720p~4
M2960 is the unique MuxKey identifier.
13466~3G~3 is the 3G asset with a DeliveryRequestId of 13466 and a successful completion status.
13467~WiFi~3 is the WiFi asset with a DeliveryRequestId of 13467 and a successful completion status.
13468~WebM~3 is the WebM asset with a DeliveryRequestId of 13468 and a successful completion status.
13469~720p~4 is the 720p asset with a DeliveryRequestId of 13469 and a failed completion status.
The DeliveryRequestId is the token used to retrieve thumbnail and movie urls. Note: The 3G asset DeliveryRequestId is used to retrieve thumbnails.
Currently the valid asset types are:
3G used for the iPhone (low bandwidth)
WiFi used for the iPhone (high bandwidth)
WebM used for desktop browsers
720p used on all platforms (very high bandwidth)
The completion status is as follows:
-1: waiting on another process
0: not yet started
1: about to start
2: in progress
3: finished (success)
4: finished (failed)
Finally, a MuxKey can also contain information about the download status of an asset:
M2962,-1~3G~2,-1~WiFi~2,-1~WebM~2,-1~720p~2,-1~(Downloading 12.3M of 16.5M)~2
M2962,13474~3G~2,13475~WiFi~2,13476~WebM~2,13477~720p~4,-1~(Downloading Complete)~3
Notes: 720p will only succeed only if the source movie is high-def. The 3G asset can be used on Safari, the Wifi asset is used on IE, Chrome, and Safari. The WebM asset is pretty much only used on Firefox, however Chrome could use the WebM asset as well if the WiFi asset wasn't generated yet.
A movie url is created by combining a DeliveryRequestId and a subType.
http://delivery.eqnetwork.com/service/store/get/?drid=13474&subType=3g
drid=13474 is a DeliveryRequestId of 13474
subType=3g specifies a 3g movie asset
In most cases the subType is the same (or similar) to the asset type returned with the DeliveryRequestId in the MuxKey:
3G: use 3g for subType
WiFi: use iphonewifi for subType
WebM: use webm for subType
720p: use 720p for subType
A movie preview url is created by combining a DeliveryRequestId and a subType.
http://delivery.eqnetwork.com/service/store/get/?drid=13474&subType=mpx
drid=13474 is the 3G asset DeliveryRequestId
subType=mpx specifies that the returned movie should be a 30 second preview.
A thumbnail is created by combining a DeliveryRequestId and a subType.
http://delivery.eqnetwork.com/icons/mgen/overplayThumbnail.ms?drid=13474&subType=ljpg&w=120&h=90&o=0
drid=13474 is the 3G asset DeliveryRequestId
subType=ljpg specifies that the returned thumbnail be a jpg.
w=120 is the maximum width for the retrieved image.
h=90 is the maximum height for the retrieved image.
o=0 specifies if a "play button" image is overlayed (0: no, 1: yes)
A 20 frame animated gif thumbnail is created by combining a DeliveryRequestId and a subType.
http://delivery.eqnetwork.com/service/store/get/?drid=13474&subType=gif
drid=13474 is the 3G asset DeliveryRequestId
subType=gif specifies that the returned thumbnail be an animated gif.
Note: This will generate a 90 x 90 size thumbnail.
The user icons filename is available as an attribute called IconFilename on a User node. Also, it is sometimes available in other nodes and called OwnerUserIconFilename.
The url to retrieve a user icon is as follows:
file=UserIcons/eedda75b-0b35-425c-bf72-9effa931907e.tiff is the path to the IconFilename
(eedda75b-0b35-425c-bf72-9effa931907e.tiff is the IconFilename in this example).
w=80 is the maximum width for the retrieved image.
h=80 is the maximum height for the retrieved image.
The collection icons filename is available as an attribute called IconFilename on a Collection node.
The url to retrieve a collection icon is as follows:
file=CollectionIcons/2b6a6503-db21-4a34-a496-1f488de5c5c3.jpg is the path to the IconFilename
(2b6a6503-db21-4a34-a496-1f488de5c5c3.jpg is the IconFilename in this example).
w=80 is the maximum width for the retrieved image.
h=80 is the maximum height for the retrieved image.
top |
User_AcceptAgreement.aspx will accept an agreement for a user. User_ResendConfirmationEmail.aspx will resend the confirmation email that is sent in User_Create.aspx. User_EmailAccounts.aspx, User_RequestPasswordReset.aspx and User_ResetPassword.aspx are used for retrieving account and resetting password information.
An Agreement must be accepted by a User before certain tasks can be performed.
Note: A lower version number will not replace a higher version number in the database.
Xml Response:
If you are returned an Ok, the user agreement version was updated normally.
This will resend the confirmation email originally sent in User_Create.aspx. SessionGuid identifies the user whose confirmation email will be resent.
Xml Response:
If you are returned an Ok, the confirmation email was resent successfully.
This will email all accounts with a given email address to that email address. Email is the given email address.
Xml Response:
If you are returned an Ok, the accounts email was resent successfully.
This will email a link to the users email address that will cause the password to be reset when clicked. UserName is the UserName of the account to email.
Xml Response:
If you are returned an Ok, the password reset email was resent successfully.
This will reset the users password to a new value. ResetPasswordGuid this is a guid that generated by the email in User_RequestPasswordReset.aspx.
Xml Response:
If you are returned an Ok, the password reset email was resent successfully.
top |
Collection_Viewed.aspx will record when a collection was viewed by a specific user.
This records when a collection was viewed by a specific user. SessionGuid identifies the user who viewed a collection.
Xml Response:
If you are returned an Ok, the collection was recorded as viewed by this user.
top |
ContentFile_Viewed.aspx will record when a content file was viewed by a specific user.
This records when a content file was viewed by a specific user. SessionGuid identifies the user who viewed a content file.
Xml Response:
If you are returned an Ok, the content file was recorded as viewed by this user.
This posts message of the specified action type to linked social services. SessionGuid identifies the user that performed an action on a content file.
Xml Response:
If you are returned an Ok, the action was sent to the social service(s). Note: This will force the notification even if social is turned off and/or the particular action is turned of.
This will unpost the most recent message of the specified action type, for this content file, from linked social services. SessionGuid identifies the user that performed an action on a content file.
Xml Response:
If you are returned an Ok, the action was sent to the social service(s). Note: This will force the notification even if social is turned off and/or the particular action is turned of.