세션 매니저 API 가이드

워터마크 삽입 전처리를 마친 ‘0’과 ‘1’ 두 버전의 콘텐츠(DASH 또는 HLS)는 사용자의 재생 요청 시에 실시간으로 조합되어 클라이언트에 전달됩니다. PallyCon 포렌식 워터마킹 서비스에서 제공하는 세션 매니저는 해당 재생 세션의 정보와 조합할 콘텐츠 URL을 입력받아, 최종 사용자에게 전달될 세션 URL을 생성합니다.

서비스 사이트는 CDN의 워터마크 믹서 연동을 통해 세션 URL에 따라 조합된 콘텐츠를 클라이언트에 스트리밍합니다. CDN 믹서 모듈에 대한 설명은 해당 가이드를 참고하시기 바랍니다.

sequenceDiagram participant A as 서비스 사이트 participant B as PallyCon 클라우드 A ->> B: 콘텐츠URL, 세션 정보 전달 Note right of B: 세션 매니저 B -->> B: 세션 키(Payload) 생성 및 세션 정보 저장 B ->> A: 세션 URL 전달

세션 매니저 API에는 아래와 같은 공통 규격이 사용됩니다.

PallyCon HTTP API 규격

PallyCon 서비스에서 사용하는 각종 HTTP API 요청시 아래 규격을 따릅니다.

요청 규격

Name Value
pallycon-apidata base64 Encoding ( JSON string )

요청 데이터 JSON 포맷

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

요청 데이터 명세

Name Value Required Description
data String Y 각 API마다 정의된 규격으로 생성한 JSON 문자열을 AES 암호화하고, 결과값을 base64 문자열로 입력
timestamp String Y GMT 시간대 기준으로 요청 시점의 시간을 “yyyy-mm-ddThh:mm:ssZ” 포맷으로 입력
hash String Y 아래 규격에 따라 생성한 해시값을 입력

AES256 Encryption

aes256 Encryption/Decryption 처리는 PallyCon Cloud 서비스 사이트 생성 시 발급 되는 Site 키 값을 이용하여 아래와 같이 처리 합니다. ( PallyCon 콘솔 사이트에서 확인 )

  • mode : CBC
  • AES key : 32 byte (PallyCon 콘솔 사이트에서 발급 되는 site key)
  • AES IV : fixed 16 byte (0123456789abcdef)
  • padding : pkcs7

SHA256 message Format

SHA256 해시의 입력값은 다음과 같은 문자열을 조합해 입력합니다.

  [site access key] + [site_id] + [json.data] + [json.timestamp]
  • site access key: PallyCon Cloud 서비스 사이트 생성 시 발급 되는 access key 값이며 PallyCon 콘솔 사이트에서 확인 가능합니다.
  • sha256 해시 함수의 결과 값은 문자열로 변환하지 않고 바이트 배열 형태 그대로 base64 함수에 입력되어야 합니다.

세션 URL 요청 API

클라이언트에서 재생할 세션 URL을 받아오는 API입니다. 패키징 단계에서 A/B 임베딩된 결과물의 URL과 워터마크로 삽입될 세션 정보(forensic mark)를 입력값으로 전달합니다.

요청 규격

  • PallyCon HTTP API 규격으로 호출
  • URL : https://watermark.pallycon.com/api/v2/session/watermarkUrl/{site_id}
  • Method: GET

URL의 ‘site_id’ 부분은 PallyCon 콘솔 사이트에서 발급된 실제 사이트 ID를 입력해야 합니다.

요청 데이터 JSON 포맷

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

요청 데이터 명세

Name Value Required Description
domain String Y 재생할 콘텐츠 URL의 도메인 부분 (예: cdn.yoursite.com)
output_path String Y 워터마크 패키징 요청 시 입력하였던 output_path
cid String Y 콘텐츠의 고유 ID
streaming_format String Y 콘텐츠의 스트리밍 유형 (dash 또는 hls)
forensic_mark String Y 워터마크로 적용될 세션 데이터 (사용자 ID, 클라이언트 정보 등), 최대 254 byte, 영문 또는 숫자만 입력 가능
gop Number N 원본 동영상의 GOP 단위 (30, 60, 120 GOP 지원, 기본값 60)

응답 규격

응답 데이터 JSON 포맷

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

응답 데이터 명세

Name Value Required Description
error_code String Y “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String Y 에러 메세지 내용
data String N 성공한 경우, 변환된 세션 URL (워터마크 URL) 리턴

세션 URL 포맷: 아래 설명 참조

  • 세션 URL 포맷: <content CDN domain>/dldzkdpsxmdnjrtm/<encrypted payload>/<output_path>/<cid>/<stream format>/<manifest file>

  • 세션 URL 구성

    항목 설명
    content CDN domain 콘텐츠를 서비스하는 CDN의 도메인명. 요청 데이터의 도메인 값을 기준으로 설정됨
    dldzkdpsxmdnjrtm 미리 정의된 고정 키워드
    encrypted payload 세션 매니저에서 생성된 세션 키(Payload)를 암호화한 데이터
    output_path 콘텐츠가 저장된 경로. 요청 데이터의 콘텐츠 URL을 기준으로 설정됨
    cid 콘텐츠의 고유 ID (ContentID)
    stream foramt 콘텐츠의 스트리밍 유형에 따라 ‘dash’ 또는 ‘hls’ 입력됨
    manifest file 스트리밍 유형에 따라 ‘stream.mpd’ 또는 ‘master.m3u8’ 입력됨

에러 코드

Code Description
0000 성공
A1000 잘못된 파라미터 값이 입력됨
A1002 Timestamp 형식이 잘못됨
A1003 Site ID를 찾을 수 없음
A1006 해당 사이트 키로 복호화에 실패함
A1007 해시 검증이 실패함
A4002 워터마크 데이터의 저장이 실패함
A4003 워터마크 데이터의 생성이 실패함
A7008 API 데이터 파싱 오류
A7009 API 버전이 맞지 않음