Session Manager API Guide

After pre-processing of watermark embedding, the ‘0’ and ‘1’ versions of content (DASH or HLS) are mixed in real time and delivered to the client on the user’s playback request. PallyCon Forensic Watermarking service provides the session manager which generates the mixed content URL with the information of the playback session.

The service site streams the mixed content to the client according to the mixed URL through the CDN’s watermark mixer integration. For a description of the CDN mixer module, please refer to the Mixer Guide.

sequenceDiagram participant B as Service site participant D as PallyCon service B ->> D: Content URL, Session data Note right of D: Session manager D -->> D: Generate session key(payload) and store session data D ->> B: Send Session URL

The session manager API uses the following common specifications:

PallyCon HTTP API Specification

The HTTP API requests used by the PallyCon service follow the specifications below.

Request

Name Value
pallycon-apidata base64 Encoding ( JSON string )

Request Data JSON Format

{
    "data":"{base64 encode(aes256 cbc encrypt(API data))}",
    "timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
    "hash":"{base64 encode(sha256(message format))}"
}

Request Data Specification

Name Value Required Description
data String Y AES encryption on the JSON string generated by the specification for each API, and the result value is input as a base64 string.
timestamp String Y Enter the time of the request at the GMT time zone in “yyyy-mm-ddThh: mm: ssZ” format.
hash String Y Enter the hash value generated according to the following specification.

AES256 Encryption

Aes256 encryption / decryption processing is performed as below using the site key value issued when joining PallyCon service. (Check PallyCon Console site)

  • mode : CBC
  • AES key : 32 byte (Site key issued from PallyCon Console site)
  • AES IV : fixed 16 byte (0123456789abcdef)
  • padding : pkcs7

SHA256 message Format

The input value of the SHA256 hash is a combination of the following strings.

[site access key] + [site_id] + [json.data] + [json.timestamp]
  • site access key: It is the access key value that is issued when creating PallyConsole Cloud service site. It can be checked on the PallyCon Console page.
  • The resulting value of the sha256 hash function must be entered into the base64 function as a byte array type, not as a string.

Session URL Request API

An API that receives the session URL to play on the client. The input values of the request are the URL of the watermark A/B embedding result and the session information (forensic mark) to be inserted as a forensic watermark of the stream.

Request

  • Called by PallyCon HTTP API specification
  • URL : watermark.pallycon.com/api/v2/session/watermarkUrl/{site_id}
  • Method: GET

You need to replace ‘site_id’ part with your siteID issued by PallyCon console.

Request Data JSON Format

{
    "domain": {domain},
    "output_path": {output_path},
    "cid": {cid},
    "streaming_format": {streaming_format},
    "forensic_mark": {forensic_mark},
    "gop": {30/60/120}
}

Request data specification

| Name | Value | Required | Description |
| ---- | ----- | ---- | -------------- |
| `domain` | String | Y | Domain of content URL (e.g. cdn.yoursite.com) |
| `output_path` | String | Y | The output_path that was entered when requesting watermark packaging |
| `cid` | String | Y | Unique content ID |
| `streaming_format` | String | Y | Streaming protocol ("dash" or "hls")|
| `forensic_mark` | String | Y | Session data to be inserted as watermark (such as end user ID, device info, etc.), max 254 byte alphanumeric characters |
| `gop` | Number | N | GOP of original video (support 30, 60, 120 GOP, default 60) |

Response

Response Data JSON Format

{
    "error_code": {error_code},
    "error_message": {message},
    "data": {watermark_url}
}

Response data specification

| Name | Value | Required | Description |
| ---- | ---- | --- | -------------- |
| error_code | String | Y | "0000" if succeeded, alphanumeric error code if failed |
| error_message | String | Y | Error message |
| data | String | N | If succeeded, returns the Session URL<p>Please see below for detailed Session URL format |
  • Session URL format: <content CDN domain>/dldzkdpsxmdnjrtm/<encrypted payload>/<output_path>/<cid>/<stream format>/<manifest file>

  • Session URL specification

    Item Description
    content CDN domain Domain name of content’s CDN. Set based on the domain in the request data
    dldzkdpsxmdnjrtm Pre-defined keyword
    encrypted payload Encrypted session key (payload)
    output_path Path of the packaging output on the storage.
    cid Unique ID of the content (ContentID)
    stream format Streaming protocol of content. (‘dash’ or ‘hls’)
    manifest file Manifest filename (‘stream.mpd’ or ‘master.m3u8’)

Error code

Code Description
0000 Succeeded
A1000 Invalid input parameter
A1002 Invalid timestamp format
A1003 Can not find the site ID
A1006 Failed to decrypt with the site key
A1007 Failed to verify the hash
A4002 Failed to store watermark data
A4003 Failed to create watermark data
A7008 API data parsing error
A7009 Invalid API version