Skip to content
Categories:
  • No categories

SCTP

Simple Content Transaction Protocol
Specification Version 0.6


SCTP is a protocol specification for content transactions, device and account authorization.

Like all SIMS protocols, this standard defines a set of resources or “actions” in the form of an HTTP GET (or POST) request which returns a response in XML or JSON format. The HTTP method does not strictly conform to REST conventions, as GET may represent retrieval, creation, modification or deletion of data on the server. POST is required only when the client is posting a large amount of data to the server, such as a bulk load of content metadata. All actions are assumed to use HTTP GET unless marked otherwise.

The location of the RADL of a SIMS protocol is discovered via the SCDL service description page. Therefore the only URL which a device must know ahead of time is the location of the SCDL service description page, and this may be posted on an informational page on the service’s web site. The recommended URL for such a page is http://hostname/sims. This makes it easy for anyone to figure out how to connect to your service.

Note: Each RADL of a SIMS protocol may define a resource path with implicit SIMS parameter values, meaning some SIMS parameter values are not included in the request but they are assumed in the path. Such resources defined in a RADL of a SIMS protocol implementation: a) must include a “sims:action” attribute within the method element where applicable, and the attribute value is the name of the SIMS action, b) must include a “sims:implicit” element within the request element where applicable, and its value is the value of an implied SIMS param value and its “param” attribute contains the implicit SIMS param name, c) must always use SIMS parameter names where applicable, and d) should include a “doc” element which contains one or more example request URIs each with a description of the equivalent SIMS action and parameters.

Example SIMS action URL with implicit parameter values:

http://hostname/browse/shows/234/seasons

This example URL is for an SCBP “search” action, and it returns a list of seasons for the show with an id value of 234. In this example, “234″ is an explicit value for the show id parameter. In this case the id value is passed as part of the url path, instead of a query parameter. The “/seasons” section of the url path represents an implicit parameter value with the meaning: type=”seasonal_series”. The meaning of this implicit parameter value would be discovered via the service’s SCBP WADL.

Each response must include <sctp> as the primary element with a version attribute indicating the specification version in the format #.#. See the SCTP XML Schema for a complete specification of the SCTP response objects.

SCTP XML Schema

1) Action: capabilities

Retrieves a description of the SCTP capabilities of the service.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.

Example capabilities Action:

action url: http://hostname/sctp/capabilities

Example XML Response:

<sctp version=x.x>
    <response>
        <code>1</code>
        <message>Success.</message>
    </response>
    <capabilities>
        <password_length>6-8</password_length>    [A]
        <password_char>upper,lower,number</password_char>    [B]
        <concurrent_views>3</concurrent_views>    [B]
        <downloads>
        </downloads>    [C]
        <streams>
        </streams>    [C]
        <manifests>
        </manifests>    [C]
    </capabilities>
</sctp>

[A] The format is #-#, where the first number is an integer between 0 and 50 which represents the minimum number of characters in an acceptable password, and the second number is an integer between 0 and 50 which represents the maximum number of characters in an acceptable password. A value of 0-0 means that no password is necessary.

[B] Contains a comma-separated list of at least one of the following: upper, lower, number. The inclusion of upper indicates that at least one upper case letter must be present in an acceptable password. The inclusion of lower indicates that at least one lower case letter must be present in an acceptable password. The inclusion of number indicates that at least one number must be present in an acceptable password.

[D] Contains an integer indicating the number of calendar days during which a viewer may watch a rented content item after the rental transaction is completed (in case of streaming) or initial successful download of the item occurs (in case of download) or, in the case where a rental_window is defined, after initial successful start of playback of the item occurs.

[E] Contains an integer indicating the number of calendar days during which a viewer may begin the rental period upon initial successful start of playback. If this element is absent or empty, then the client may assume that the rental period begins upon initial successful download of the item, or in the case of streaming, upon rental transaction completion.

Possible Response Codes:

1 (success)
-1 (unknown error)
-12 (extended error information available)
-24 (missing element)


2) Action: login

When successful, this action logs a user into an account and establishes a session with the service. A response may include a displayName element to indicate the display name of the account. A session id is included in the response, and this id is used for all SIMS actions which require an authenticated account. The account_login action does NOT require the session parameter for obvious reasons.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session.
username* (string)
The username of the account. This can be any alphanumeric string including any characters which are allowed in an Internet email address. In some cases the service may allow “anonymous” with no password.
password* (string)
The password for the account. Not needed if device_code is used. This can be any alphanumeric string including “!@#$%^&*()_+-=<>.{}[]|”. It may be hashed or encrypted depending upon the digest parameter. This may be empty if username is “anonymous”.
device_code* (string)
The device code for the device, specific to an account. Not needed if password is used. This can be any alphanumeric string including “!@#$%^&*()_+-=<>.{}[]|”. It may be hashed or encrypted depending upon the digest parameter. This may be empty if username is “anonymous”.

Example login Action:

action url: http://hostname/sctp/login
username: user@domain.com
password: ********

Example XML Response:

<sctp version=x.x>
    <response>
        <code>1</code>
        <message>Your transaction was completed.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
    <display_name>John Doe</display_name>    [A]
</sctp>

[A] The account name which can be displayed by the client when logged in to the service. This is typically in the format “Firstname Lastname”.

Possible Response Codes:

1 (success)
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


2) Action: validate_pin

When successful, this action validates an accounts PIN code.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
session (string)
The session id of the account authenticated session.
pin (string)
The PIN code for the account.
type* (string)
The type of PIN code. Must match the type string as defined by the service.

Example validate_pin Action:

action url: http://hostname/sctp/validate_pin
session: 348t39ghqi4ho3u4
pin: ********

Example XML Response:

<sctp version=x.x>
    <response>
        <code>1</code>
        <message>Success.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


3) Action: purchase

When successful, this action executes a purchase transaction.

Method: HTTP POST

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session.
pin (string)
The PIN code is optional depending on the requirement of the service.
type (string)
This string must match one of the item types supported by the service. (See SCBP)
id (string)
This string is a case-sensitive alphanumeric string with no punctuation or spaces.

Example purchase Action:

action url: http://hostname.com/sctp/purchase
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
type: episodes
id: 2989

Example XML Response:

<sctp version=x.x>
    <response>
        <code>-5</code>
        <message>You have already purchased this content.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-3 (content not valid)
-4 (content not available)
-5 (already purchased)
-8 (user not logged in)
-12 (extended error information available)
-24 (missing element)

Note: Success returns Download URL or URL to volume RSS feed. Type form element may be extended by using “x-” at the beginning of the element value, indicating an custom type.


4) Action: rent

When successful, executes a rental transaction, allowing rental for a specified period of time.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session.
pin (string)
The PIN code is optional depending on the requirement of the service.
type (string)
This must be one of the following: movie, episode, season, song, music_album or audio_book
id (string)
This string value is the content ID.

Example rent Action:

action url: http://hostname.com/sctp/rent
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
type: episodes
id: 2989

Example XML Response:

<sctp version=x.x>
    <response>
        <code>-16</code>
        <message>'You have already rented this item.'</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-3 (content not valid)
-4 (content not available)
-8 (user not logged in)
-12 (extended error information available)
-16 (already rented)
-24 (missing element)

Note: Success returns Download URL or URL to volume RSS feed. Type form element may be extended by using “x-” at the beginning of the element value, indicating an custom type.


5) Action: media

When successful, this action returns a list of stream and download elements containing urls to retrieve the playable media (specific to format) as well as any necessary DRM token for each. Playable media have GUIDs which uniquely identify the playable content item in a specific format. For example, a TV episode which has ID=234 may have many playable media associated with it, one for each format. Each playable media has a GUID which identifies the specific downloadable file or accessible stream in the specific format.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies or content does not require user authentication.
type (string)
This must be one of the following: movie, episode, song, audio_book, ad
id (string)
The id of the item to be retrieved. This is not the content guid, but the id of the episode or movie, etc.

Example media Request:

action url: http://hostname.com/sctp/media
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
type: episode
id: 3006

Example XML Response:

<sctp version=x.x>
    <response>
        <code>1</code>
        <message>Your content request is approved.</message>
    </response>
    <streams>
        <stream>
            <guid>234<guid>    [A]
            <format>str1</format>    [B]
            <url>http://hostname.com/streams/234.adf45gthwgqef3fqefqefqe</download>    [C.1]
        </stream>
        <stream>
            <guid>235<guid>
            <format>str2</format>
            <url>http://hostname.com/streams/235.wrthf43t3rgwegqegq</download>    [C.2]
            <vfs>http://hostname.com/streams/235vfs.welfj34wedfweiw3</vfs>
        </stream>
    </streams>
    <downloads>
        <download">    [D]
            <guid>244<guid>
            <protocol>http</protocol&gt    [D]
            <format>sd1</format>
            <url>http://hostname.com/download/234</url>
            <digest>http://hostname.com/download/234</digest>    [E]
            <digest_algorithm>md5</digest_algorithm>
            <drm type="marlin-bb">    [F]
                ...
            </drm>
        </download>
    </downloads>
    <session>348t39ghqi4ho3u4</session>
</sctp>

[A] Zero or more stream elements are allowed. Stream elements contain the guid, format and url for a particular stream available on the service.

[B] One format element is allowed per stream. The value must match one of the names of the supported formats of the service as defined in the service’s SCBP getFormats response.

[C.1] One url element is allowed within each stream element.

[C.2] In the case of content which uses the m3u audio format container, the content url must point to an m3u playlist file which is assumed to contain a list of mp3 audio streams. In the case of content which uses the m3u-ts video format container, the content url must point to a live streaming m3u8 file in the format defined by the IETF Internet Draft draft-pantos-http-live-streaming-02. In the case of content which uses the bdmv-ts video format container, the content URL is a live streaming m3u8 file, and an additional element must be present within the element, and it must point to the url to obtain the jar file for the VFS image.

[D.1] Zero or more download elements are allowed. Download elements should be nested within a downloads element. Download elements contain the guid, format, url and if necessary any DRM data for a particular downloadable content item available from the service.

[D.2] Indicates the content download methods supported by the service. Not all content may be available via any or all download methods. A device must discover the allowed download methods for each content item through an SCBP search. The following values are defined for the download element:
http, https, ftp, ftps, sftp

[D.3] Zero or more stream elements are allowed. Stream elements should be nested within a streams element. Stream elements contain the guid, format, url and if necessary any DRM data for a particular downloadable content item available from the service.

[D.4] Indicates the content streaming methods supported by the service. Not all content may be available via any or all streaming methods. A device must discover the allowed streaming methods for each content item through an SCBP search. The following values are defined for the streaming element:
http, https, rtsp, rtmp, rtmpe

[D.5] Zero or more manifest elements are allowed. Manifest elements should be nested within a manifests element. Manifest elements contain the guid, format, url, type (ex. “hls”) and if necessary any DRM data for a particular downloadable content item available from the service.

[F] Zero or one drm element is allowed within each download, stream or manifest element. This contains any DRM data necessary to acquire a DRM license for the content. The drm element includes an attribute type with a value which must match one of the DRMs supported by the service as stated in the SCDL service description.

Possible Response Codes:

1 (success)
-1 (unknown error)
-3 (media not valid)
-7 (user not authorized)
-8 (user not logged in)
-12 (extended error information available)
-24 (missing element)


5) Action: manifest

When successful, this action returns an m3u8 or other format manifest.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device* (string)
The device id of the device performing the action. This is not required if session is provided.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies or content does not require user authentication.
type (string)
This must be one of the following: movie, episode, song, audio_book, ad
id (string)
The id of the item to be retrieved. This is not the content guid, but the id of the episode or movie, etc.

Example manifest Request:

action url: http://hostname.com/sctp/manifest
session: 348t39ghqi4ho3u4
type: episode
id: 3006

6) Action: allow_previews

When successful, this action allows protected content previews to be played on the device. The action returns the proper DRM action token(s) to initiate a node and link acquisition to the DRM preview node.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies.

Example allow_previews Action:

action url: http://hostname.com/sctp/allow_previews
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4

Example XML Response:

<sctp version="x.x">
    <response>
        <code>-14</code>
        <message>This device is not yet registered with the service. Please ensure your Internet connection
        is working correctly. Device registration automatically occurs.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-12 (extended error information available)
-14 (device not personalized)
-24 (missing element)


7) Action: preview

When successful, this action retrieves a content preview. Success returns a URL to the content preview file and a DRM action token if required.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies.
type (string)
The type of item to be previewed. This must be one of the following: movie, episode, song or audio_book
id (string)
The id of the item to be previewed.

Example preview Request:

action url: http://hostname.com/sctp/preview
device: we7r8h3406ty349thom34t
session: 348t39ghqi4ho3u4
type: episode
id: 3006

Example XML Response:

<sctp version="x.x">
    <device> we7r8h3406ty349thom34t</device>
    <response>
        <code>-3</code>
        <message>The content you requested is not valid.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-3 (content not valid)
-12 (extended error information available)
-24 (missing element)


8) Action: register_device

When successful, this action registers a new user device with the service. Success returns any necessary DRM tokens if required as well as the id of the device. The service may choose to ignore uniqueness of fingerprints, and always create a new device entry with a new device ID returned. If a service requires unique fingerprints for device registration, then a duplicate fingerprint on registration will return an error.

Parameters: (* is optional):

output* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
uuid (string)
This is any string derived by the device to attempt to uniquely identify the device, such as a serial number.
device_type* (string)
This must match one of the device_types defined in the SCDL service description.
developer_code (string)
This is a case-insensitive alphanumeric unique (within the service) id which is assigned by the service. This code is used to verify that the developer of the device (or at least the application running on the device) has been approved by the service, and therefore the device is trusted to comply with the operating requirements of the service.
manufacturer* (string)
This is a case-insensitive alphanumeric unique (within the service) id which may include only “-” and “.” punctuation and no spaces. This should represent the manufacturer of the device.
device_model* (string)
This is a case-insensitive alphanumeric unique (within the manufacturer scope) id which may include only “-” and “.” punctuation and no spaces.
platform* (string)
This is a case-insensitive alphanumeric unique (within the service) id which may include only “-” and “.” punctuation and no spaces.
platform_version* (string)
This must be in the format “x”, “x.x” or “x.x.x” where each section “x” may be any alphanumeric value. In order to support SSUP properly, higher values must represent higher versions.
software* (string)
This is a case-insensitive alphanumeric unique (within the service) id which may include only “-” and “.” punctuation and no spaces.
software_version* (string)
This must be in the format “x”, “x.x” or “x.x.x” where each section “x” may be any alphanumeric value. In order to support SSUP properly, higher values must represent higher versions.
label* (string)
This is the user created name which may contain any character.

Example register_device Action:

action url: http://hostname.com/sctp/register_device
device_type: home
developer_code: 34tk3l34tl3k4tlk4t3l5k4l5k
uuid: 43tergEr3Dr5gr454
manufacturer: the-big-company
device_model: tv-100
software: tv-app
software_version: 3.4.0

Example XML Response:

<sctp version="x.x">
    <response>
        <code>1</code>
        <message>Device registration complete.</message>
    </response>
    <device>we9r8g3409ty349grif34t</device>
    <access_code>GHNIFX</access_code>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-9 (device already registered)
-10 (device limit exceeded)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


8) Action: authorize

When successful, this action authorizes a user device to access and play content. Success returns any necessary DRM tokens and/or device code if required.

Parameters: (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
This is the unique (within the service) device ID which is provided by the service. It may have been embedded within the device during manufacturing, or it may have been provided by the service to the device through a DRM registration process, or some other way. Typically a device will know it’s ID prior to authorization. A service may allow devices which do not yet have an ID to request authorization to an “anonymous” account. For example, the service may allow a device which can only play streams of free ad-supported content. In this case, the device will not include an ID parameter in the request, but will receive a new device ID in the response, if allowed.
session* (string)
The session id of the account authenticated session. It is not necessary to include a session id if the device was linked by the user through a link access code, such as via the web site of the service. Session id is also optional if session is handled via cookies.
access_code* (string)
This is the access code provided by the register_device action. It is not necessary if the device was linked by the user through an alternative method, such as via the web site of the service.

Example authorize Action:

action url: http://hostname.com/sctp/authorize
session: 348t39ghqi4ho3u4
device: we9r8g3409ty349grif34t

Example XML Response:

<sctp version="x.x">
    <response>
        <code>1</code>
        <message>Device authorized.</message>
    </response>
    <device_password>we9r8g3409</device_password>
    <account>
        <display_name>User Name</display_name>
    </account>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-9 (device already authorized)
-10 (device limit exceeded)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


9) Action: deauthorize

When successful, this action deauthorizes a device from playing copy-protected content. Success returns one or more DRM action tokens if required. The server may enforce a maximum number of devices per account.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies.
device_password* (string)
The password for the device-account pair. Not needed if session id or session cookie is used. This can be any alphanumeric string including “!@#$%^&*()_+-=<>.{}[]|”.

Example deauthorize Action:

action url: http://hostname.com/sctp/deauthorize
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4

Example XML Response:

<sctp version="x.x">
    <response>
        <code>-2</code>
        <message>This device is not currently authorized for your account.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-2 (device not authorized)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


10) Action: license

When successful, this action retrieves a license for the requested content.

Parameters (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies or content does not require user authentication.
type (string)
This must be one of the following: movie, episode, podcast_episode, song, audio_book or ad
id (string)
The guid of the content item associated with the license.

Example license Request:

action url: http://hostname.com/sctp/license
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
type: episodes
id: 2446

Example XML Response:

<sctp version="x.x">
    <response>
        <code>1</code>
        <message>Success</message>
    </response>
    <drm type="marlinbb">
        ...
    </drm>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-3 (content not valid)
-7 (user not authorized)
-8 (user not logged in)
-12 (extended error information available)
-24 (missing element)


14) Action: add_favorite

When successful, this action adds an item to the account’s list of favorites.

Method: HTTP POST

Parameters: (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies.
id (string)
The id of the item to be added.
type (string)
The item type of the item to be added.

Example add_favorite Action:

action url: http://hostname.com/sctp/addfavorite
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
id: 234
type: show

Example XML Response:

<sctp version=x.x>
    <response>
        <code>1</code>
        <message>The item was added to your favorites.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


15) Action: remove_favorite

When successful, this action removes an item from the account’s list of favorites.

Method: HTTP DELETE (or POST with parameter “_method=delete” OK)

Parameters: (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies.
id (string)
The id of the item to be removed.
type (string)
The item type of the item to be removed.

Example remove_favorite Action:

action url: http://hostname.com/sctp/removefavorite
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
id: 234
type: show

Example XML Response:

<sctp version=x.x>
    <response>
        <code>1</code>
        <message>The item was removed from your favorites.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


14) Action: add_bookmark

When successful, this action adds an item to the account’s list of content bookmarks.

Method: HTTP POST

Parameters: (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies.
id (string)
The id of the item to be bookmarked.
type (string)
The item type of the item to be bookmarked.
position (string)
The time position within the content. This is an integer representing the number of seconds from the beginning.
name* (string)
The name of the bookmark. The name “*” is reserved for the case where a bookmark is intended to be a resume mark (the point at which the user paused playback to resume later). Only one resume mark per content item may be set within the scope of a particular account. If a second resume mark is set on the same content item for the same account, the service must replace the previous resume mark with the new one. For information on how to obtain a list of bookmarks or a resume mark for a content item, see the SCBP specification.

Example add_bookmark Action:

action url: http://hostname.com/sctp/addbookmark
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
id: 234
type: show
position: 00:34:02
name: My favorite scene

Example XML Response:

<sctp version=x.x>
    <response>
        <code>1</code>
        <message>The item was added to your bookmarks.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


15) Action: remove_bookmark

When successful, this action removes an item from the account’s list of content bookmarks.

Method: HTTP DELETE (or POST with parameter “_method=delete” OK)

Parameters: (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies.
id (string)
The id of the bookmarked item.
type (string)
The item type of the bookmarked item.
position (string)
The time position of the bookmark within the content. This is an integer representing the number of seconds from the beginning.

Example remove_bookmark Action:

action url: http://hostname.com/sctp/removebookmark
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
id: 234
type: show
position: 00:43:02

Example XML Response:

<sctp version=x.x>
    <response>
        <code>1</code>
        <message>The item was removed from your bookmarks.</message>
    </response>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


16) Action: playlog

When successful, this action updates the service with recent playlog data for the device on the account. The playlog includes a listing of all instances of content playback and ad playback. The response includes an items element which contains the number of playlog items added during the update.

Method: HTTP POST

Parameters: (* is optional):

ouput* (string)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session. Optional if session is handled via cookies.
type (string)
The type of playlog, one of the following values: content, ads
playlog (string)
The playlog of content from the time of last successful update. The format is:

yyyy-mm-dd-hh:mm:ss,yyyy-mm-dd-hh:mm:ss,ss,ss,guid&…

where the first and second date-time is the calendar play start and stop time respectively, the following two integers are the number of seconds from the beginning of the content (or ad) where started and stopped respectively, and the guid is of the specific content (or ad) file viewed.

Example playlog Action:

action url: http://hostname.com/sctp/updatePlaylog
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
type: content
playlog: 2009-08-10-20:03:32,2009-08-10-20:13:20,00:03:02,00:13:02,234&2009-08-10-20:05:03,
2009-08-10-20:05:18,00:00:00,00:10:03,453&2009-08-10-21:03:32,2009-08-10-20:13:20,00:03:02,00:13:02,
2344&2009-08-10-20:05:03,2009-08-10-22:05:18,00:00:00,00:10:03,2353

Example XML Response:

<sctp version=x.x>
    <response>
        <code>1</code>
        <message>The playlog was successfully updated.</message>
    </response>
    <items>4</items>
    <session>348t39ghqi4ho3u4</session>
</sctp>

Possible Response Codes:

1 (success)
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)


Response Code Glossary:

1 (success)
Suggested description message: ‘Your transaction was completed.’
-1 (unknown error)
Suggested description message: ‘There was an unknown error.’
-2 (device not authorized)
Suggested description message: ‘This device is not currently authorized for your account.’
-3 (content not valid)
Suggested description message: ‘The content you requested is not valid.’
-4 (content not available)
‘Suggested description message: ‘The item you requested is not available.’
-5 (already purchased)
Suggested description: ‘You have already purchased this content.’
-6 (already subscribed)
Suggested description message: ‘You have already subscribed to this content.’
-7 (user not authorized)
Suggested description message: ‘Sorry, you are not currently subscribed to this channel or show, or you have not purchased or rented this item. Please subscribe, purchase or rent this item.’
-8 (user not logged in)
Suggested description message: ‘You are not currently logged in. Please log in.’
-9 (device already authorized)
Suggested description messages: ‘This device is already authorized for your account.’
-10 (device limit exceeded)
Suggested description message: ‘You have already reached the maximum number of authorized devices for your account. You can deauthorize a device in order to authorize this device.’
-11 (user already registered)
Suggested description message: ‘You are already registered.’
-12 (extended error information available)
Suggested description message: ‘There is more information available for this error.’
-13 (invalid credentials)
Suggested description message: ‘The username and password entered is not valid. Please re-enter your username and password.’
-14 (device not personalized)
Suggested description message: ‘This device is not yet registered with the service. Please ensure your Internet connection is working correctly. Device registration automatically occurs.’
-15 (not subscribed)
Suggested description message: ‘You are currently subscribed to this channel or show.’
-16 (already rented)
Suggested description message: ‘You have already rented this item.’
-17 (input absent)
Suggested description: ‘There is an input missing. Please fill in all required information.’
-18 (gateway failure)
Suggested description message: ‘The Payment Gateway is currently unavailable. Please try again later.’
-19 (payment failure)
Suggested description message: ‘Your payment could not be processed. Please try again with a valid payment method.’
-20 (transaction denied)
Suggested description message: Sorry, you can only purchase 5 individual episodes with this account.’
-21 (device location restricted)
Suggested description message: ‘The device you are trying to authorize does not appear to be located in the appropriate region.’
-22 (inactive account login)
Suggested description message: ‘This account is not yet active. Please activate this account before attempting to log in.’
-23 (inappropriate value)
Suggested description message: ‘One or more form elements contain an inappropriate value.’
-24 (missing element)
Suggested description message: ‘One or more required form elements are missing.’

Note: For extended error information there is an optional element “error” which is a sibling to code and message elements, containing additional textual error data for the client to display.


By admin 12:19 am

0 Responses

Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.



Some HTML is OK

or, reply to this post via trackback.