Skip to content
Categories:
  • No categories

SARP

Simple Advertisement Retrieval Protocol
Specification Version 0.6


SARP is a protocol specification for discovery and retrieval of advertisements associated with content and/or accounts.

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 <sarp> as the primary element with a version attribute indicating the specification version in the format #.#. See the SARP XML Schema for a complete specification of the SARP response objects.

SARP XML Schema

1) Action: capabilities

Retrieves a description of the SARP 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/sarp/capabilities

Example XML Response:

<sarp version=x.x>
    <response>
        <code>1</code>
        <message>Success.</message>
    </response>
   <target_types>channels, shows</target_types>    [A]
   <target_data>gender,age_min,age_max,time_slot</target_data>    [B]
</sarp>

[A] A comma-separated list of the supported content item types which may be used as the target type in a query for targeted ads. Content item types are defined by SCBP.

[B] A comma-separated list of supported target data types. Target data types are defined by SARP.

Possible Response Codes:

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


2) Action: ad_map

When successful, this action returns commercial breaks and an ordered list of required ads for the specified content. The ad map can be used by a client to embed the required ad placement information of a content item within the content file for better portability of content files across devices. The envelope and signature is optional, depending upon the level of security desired.

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. Not needed if session id is used. 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 session id 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".
digest* (string)
This may be one of the following: md5, sha1, sha2, none. If absent or empty, then service must assume none.
guid (string)
This string value is used to represent the globally (within the service) unique ID of the content file.

Example ad_map Request:

action url: http://hostname.com/sarp/admap
guide:1234567890
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4

Example XML Response:

<sarp version="x.x">
    <response>
        <code>1</code>
        <message>Success</message>
        <count>5</count>
    </response>
    <Envelope>
        <ad_map>
            <content>
                <id>123</id>    [A]
                <type>episode</type>    [A]
                <guid>1234567890</content_guid>    [A]
                <commercial_breaks>123.11,456.22,987.33</commercial_breaks>    [B]
            </content>
            <advertisements>
                <advertisement>
                    <id>12345</id>
                    <type>commercial</type>    [C]
                    <placement_type>required</placement_type>    [D]
                    <start>2008-01-01</start>    [E]
                    <end>2008-02-01</end>    [F]
                    <duration>34</duration>    [G]
                    <force_play>true</force_play>    [H]
                    <min_play>5</min_play>    [I]
                    <streams>    [J]
                        <stream>
                            <media_guid>23423</media_guid>
                            <format>sd512</format>
                            <url>http://hostname.com/lkwheflskjdflksej</url>
                        </stream>
                        ...
                    </streams>
                    <downloads>    [K]
                        <download>
                            <media_guid>23423</media_guid>
                            <format>sd512</format>
                            <digest>23r2efh2l3kl2k3jr2l3kjr2lk3jr2</digest>
                            <digest_algorithm>sha1</digest_algorithm>
                            <url>http://hostname.com/wlekfjslidjlwefjlsdi</url>
                            <drm>
                               ...
                            <drm&gt
                        </download>
                        ...
                    </downloads>
                    <links>    [L]
                        <media>/media?type=ad&id=12345</media>
                        ...
                    </links>
                </advertisement>
                ...
            </advertisements>
        </ad_map>
        <Signature>    [M]
        ...
        </Signature>
    </Envelope>
</sarp>

[A.1] The id of the content in which the ad is placed. This is unique only within the content item type.

[A.2] The content item type of the content in which the ad is placed. This can be one of: episode, movie, song, audio_book, podcast_episode

[A.3] The content guid of the content in which the ad is placed. This is unique across all content within the service.

[B] A comma separated list of commercial break points in the content, break points are decimal seconds down to 100ths of a second (see example above).

[C] The type of ad, possible values are "commercial" for an interstitial commercial spot, and "overlay" for a graphics overlay.

[D] The type of placement for the ad, possible values are 'required' for ads which must play with the associated content, and 'targeted' for ads which may play with the associated content based upon a set of matching target data and weighting.

[E] The date-time when the ad starts running according to the placement. In the format "yyyy-mm-dd-hh:mm" or just "yyyy-mm-dd". Devices should ignore placements which are not yet running.

[F] The date-time when the ad stops running according to the placement. In the format "yyyy-mm-dd-hh:mm" or just "yyyy-mm-dd". Devices should ignore placements which have stopped running.

[G] An integer representing the length of the ad in seconds.

[H] Can be "true" or "false" indicating whether some portion of the ad must be played.

[I] An integer representing the minimum number of seconds to play the ad if the force_play value is "true".

[J] Inclusion of streams element is optional. It is an optimization, to avoid the need for an extra SCTP media action to access the media streams. The element includes the list of media streams for the ad, including the media GUID, format name and URL to access the ad stream. Keep in mind that the URL may be time sensitive, so if the ad map is stored or embedded within a client's local copy of the content file, any subsequent use of the stream URLs should be with caution as the URLs may have expired, and an SCTP media action will be needed to access a fresh URL to the ad media. If no media streams are available for the ad, then this element should be excluded.

[J] This is the list of downloadable media for the ad, including the media GUID, format name and digest of the media file. The URL and DRM elements may also be included as an optimization, to avoid the need for an extra SCTP media action to access the downloadable media files. Keep in mind that the URL may be time sensitive, so if the ad map is stored or embedded within a client's local copy of the content file, any subsequent use of the stream URLs should be with caution as the URLs may have expired, and an SCTP media action will be needed to access a fresh URL for the ad media. If no downloadable media is available for the ad, then this element should be excluded.

[K] The links element is optional. It can be used to include a set of URLs for SIMS actions which are related to the advertisement. For example, it may include a link for obtaining the media for the ad. Within the links element, the names of the child elements are service specific. It is recommended that if the link points to a search action, that the name of the link child element should be the name of the search scope (for example <episodes>), and if the the link points to an SCTP, SCSP or SARP action, that the name of the link child element should be the name of the action (for example <media>).

[L] Signature of the sarp node. In the case of XML, it is an XML-Signature. (see http://www.w3.org/TR/xmldsig-core/ and http://www.w3.org/2000/09/xmldsig)

Possible Response Codes:

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

3) Action: targeted_ads

When successful, this action retrieves ads targeted to specific content when a device plays content. This is useful when a client attempts to fill unused ad space during playback of a content item.

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. Not needed if session id is used. 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 session id 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".
digest* (string)
This may be one of the following: md5, sha1, sha2, none. If absent or empty, then service must assume none.
type (string)
This is a string value with one of the following values: channel, show, season, episode, movie, radio_station, song, audio_book
id (string)
This is a string value representing the id of the channel, show, etc.
gender (string)
This is a string value with one of the following values: male, female, both. This value only applies to channel type
age_min (integer)
Integer used to define the minimum age allowed to access content on this channel (e.g., 18, 22, etc). This value only applies to channel type.
age_max (integer)
Integer used to define maximum age allowed to access content on this channel type (e.g., 50). This value only applies to channel type.
time_slot (string)
Defines two 24hr timecodes as hh:mm separated by "-", ex: "19:00-22:00." This value only applies to channel type.
limit (integer)
Integer used to define the maximum number of results to be returned.

Example targeted_ads Request:

action url: http://hostname.com/sarp/targetedads
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
type: episodes
id: 3006
gender: female
age_min: 18
age_max: 35
time_slot: 16:00 - 18:00
limit: 10

Example XML Response:

<sarp version=x.x>
    <response>
        <code>1</code>
        <message>Success</message>
        <count>35</count>
    </response>
    <advertisements>
        <advertisement>
            <id>33</id>
            <type>commercial</type>    [C]
            <placement_type>targeted</placement_type>    [D]
            <start>2008-11-01</start>    [E]
            <end>2008-12-01</end>    [F]
            <duration>34</duration>    [G]
            <force_play>true</force_play>    [H]
            <min_play>5</min_play>    [I]
        </advertisement>
        ...
    </advertisements>
</sarp>

[C] The type of ad, possible values are "commercial" for an interstitial commercial spot, and "overlay" for a graphics overlay.

[D] The type of placement for the ad, possible values are 'required' for ads which must play with the associated content, and 'targeted' for ads which may play with the associated content based upon a set of matching target data and weighting.

[E] The date-time when the ad starts running according to the placement. In the format "yyyy-mm-dd-hh:mm" or just "yyyy-mm-dd". Devices should ignore placements which are not yet running.

[F] The date-time when the ad stops running according to the placement. In the format "yyyy-mm-dd-hh:mm" or just "yyyy-mm-dd". Devices should ignore placements which have stopped running.

[G] An integer representing the length of the ad in seconds.

[H] Can be "true" or "false" indicating whether some portion of the ad must be played.

[I] An integer representing the minimum number of seconds to play the ad if the force_play value is "true".

Possible Response Codes:

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


4) Action: target_map

When successful, this action retrieves the target map for ads. The target map can be used by a client to embed the targeted placement information of an ad within the ad file for better portability of ad files across devices. The envelope and signature is optional, depending upon the level of security desired.

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. Not needed if session id is used. 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 session id 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".
digest* (string)
This may be one of the following: md5, sha1, sha2, none. If absent or empty, then service must assume none.
id (string)
This string value is used to represent the ad ID.

Example target_map Request:

action url: http://hostname.com/sarp/targetmap
id: 1234567890
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4

Example XML Response:

<sarp version="x.x">
    <response>
        <code>1</code>
        <message>Success.</message>
    </response>
    <Envelope>
        <target_map>
            <count>12</count>
            <min_target_age>18</min_target_age>    [C]
            <max_target_age>35</max_target_age>    [D]
            <target_gender>female</target_gender>    [E]
            <placements>    [F]
                <placement>
                    <type>channel</type>    [F]
                    <id>5</id>    [F]
                    <weight>5000</weight>    [G]
                    <start_date>2008-11-01</start_date>    [H]
                    <end_date>2008-12-01</end_date>    [I]
                    <time_slot>05-11</time_slot>    [J]
                    <postal_codes>00000-00000,00000-00000,00000-00000</postal_codes>    [K]
                </placement>
                ...
            </placements>
        </target_map>
        <Signature>    [J]
        ...
        </Signature>
    </Envelope>
</sarp>

[C] An integer representing the minimum age of the target audience for the ad.

[D] An integer representing the maximum age of the target audience for the ad.

[E] The gender of the target audience for the ad. May be one of the following: male, female, both

[F] The ad may have several targeted placements. Targeted placements are ad placements against a scope of content, such as an entire TV channel, where the ad is not required to play, but is likely to play with any episode of any show in that channel having similar target data in common with the ad. The type and id elements indicate the scope of the ad placement.

[G] An integer representing the relative weight of the placement vs. other completing placements. Placements with higher value are more likely to play.

[H] The date when the ad starts running according to the placement. In the format "yyyy-mm-dd-hh:mm" or just "yyyy-mm-dd". Devices should ignore placements which are not yet running.

[I] The date when the ad stops running according to the placement. In the format "yyyy-mm-dd-hh:mm" or just "yyyy-mm-dd". Devices should ignore placements which have stopped running.

[J] The window of hours in the day during which the ad may play. In the format "hh:mm-hh:mm" where hours are "00" thru "24". For example "06:00-11:00" means from 6:00am to 11:00am.

[K] The list of postal code ranges where the ad can play. In the format "xxxxx-xxxxx,xxxxx-xxxxx,..." where "xxxxx" represents each postal code.

Possible Response Codes:

1 (success)
Suggested description message: 'Your transaction was completed.'
-1 (unknown error)
Suggested description message: 'There was an unknown error.'
-8 (user not logged in)
Suggested description message: 'You are not currently logged in. Please login.'
-12 (extended error information available)
Suggested description message:
-24 (missing element)
Suggested description message: 'One or more required form elements are missing.'


By admin 12:20 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.