Appendix

웹 소켓 이용 방법

각 클라이언트는 분산된 Node process에서 접속하더라도 공통된 세션을 공유하여 데이터를 송/수신 할 수 있습니다.

• 웹 소켓 서버 정보 (SSL만 이용 가능)
  • wss://svcapp.gigagenie.ai/channel

• WebSocket API Payload (예약어)
  • msgtype : 메시지 송/수신 유형
    ① request: 서비스 클라이언트에서의 요청, trxid를 설정해서 트랜잭션을 구분해야함
    ② reply: request에 대한 서버에서의 처리 결과 전달, trxid로 transaction 구별
    ③ notify: 서버에서 클라이언트로 전달되는 event 알림, trxid 없음
    ④ data: Data 전달, trxid 없음, 데이터 전달 채널 정보(TBD)
    
  • operation : 인증, 세션 생성/소멸, 특정 데이터 전달 등의 작업 구분자
    ① auth: 인증, 서버에 클라이언트가 인증 요청 시 사용
    ② iam: 인증, 서버에서 WebSocket 접속한 클라이언트에 notify할 때 사용
    ③ create_session: 채널 세션 생성
    ④ join_session: 생성된 채널 세션에 참여
    ⑤ ras_alive: WebSocket 연결 유지를 위한 PING-PONG시 사용
    ⑥ destroy_session: 생성된 채널 세션을 종료
    ⑦ set_input_history: 테스트를 위한 입력된 URL 저장(UUID기준, 개발자 지원)
    ⑧ get_input_history: 테스트를 위한 입력된 URL 조회(UUID 기준, 개발자 지원)
    ⑨ set_appid_devmode: 해당 APP_ID의 개발자모드 설정
    ⑩ check_appid_devmod: 해당 APP_ID가 개발자모드로 설정되있는지 확인
    ⑪ confirm_appid_devmode: 해당 APP_ID를 개발자모드로 설정(개발자 센터용, REST API로 대체 가능)
    
  • channeltype: 웹 소켓 채널의 용도 구분자
    ① rtcaudio: WebRTC 오디오 채널 유형
    ② system: 서버에서 발생하는 notify를 전달하는 채널 유형 (예, ras_alive)
    

연결 (Connection)

WebSocket Protocol은 서비스에 따라 임의로 지정하여 사용할 수 있습니다.

• WebSocket Protocol표준 준수(Header: Sec-WebSocket-Protocol)
• 연결예시) [“wss://svcapp.gigagenie.ai/channel”, “ws-channel-v1”]

인증 (AUTH)

① 최초 Client 는 서버에 WebSocket connect 를 시도합니다.
② 서버는 접속한 클라이언트에 인증이 필요함을 알립니다.

• Message sample :

  
  {
      "msgtype":"notify",
      "operation":"iam",
      "channeltype":"system"
  }
  

• Client 에서의 수신 처리는 아래의 WebSocket 클라이언트 샘플 소스 참고.

③ Client 는 인증 Request 를 통해 인증을 요청합니다.


• Message sample :

  
  {
      "msgtype":"request",
      "operation":"auth",
      "uuid":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "channeltype":"webrtcaudio"
  }
  

• Client 에서 Request 처리는 아래의 WebSocket 클라이언트 샘플 소스 참고.

④ 서버사이드에서는 내부 인증 연동을 통하여 그 결과를 reply 합니다.


• Message sample :

  
  {
      "msgtype":"reply",
      "operation":"auth",
      "channeltype":"system",
      "result_cd":200,
      "result_msg":"authorized"
  }
  

• Client 에서 Reply 처리는 아래의 WebSocket 클라이언트 샘플 소스 참고.

⑤ 인증에 성공하면 접속은 유지되고, 통신을 할 수 있는 상태가 됩니다.
⑥ 만약, 일정시간 Client 가 인증에 응하지 않으면 접속은 자동 종료됩니다.


socket.onmessage = function(message) {
    console.log('Socket server message', message.data);
    document.getElementById('response').innerHTML = message.data;
    let pdata = JSON.parse(message.data);
    console.log(pdata);
    if (pdata.msgtype === 'notify') {
        if (pdata.operation === 'iam') {
            var auth_message = {
                "msgtype": "request",
                "operation": "auth",
                "uuid": uuid,
                "channeltype": "webrtcaudio",
            };
            socket.send(JSON.stringify(auth_message));
            console.log('auth message sent.');
        }
        if (pdata.operation !== 'ras_alive') {;
        }
    } else if (pdata.msgtype === 'reply') {
        // authorized
        if (pdata.operation == 'auth') {
            if (pdata.result_cd == 200) {
                var create_session = {
                    "msgtype": "request",
                    "operation": "create_session",
                    "channeltype": "webrtcaudio",
                    "uuid": uuid,
                    "trxid": "K0000000:1501463079077:00002"
                };
                socket.send(JSON.stringify(create_session));
                console.log('create_session message sent.');
            } else {;
            }
        }
    } else if (pdata.msgtype === 'data') {;
    }
};

접속유지 (Alive test)

GATE-API Channel 서버는 접속한 클라이언트가 일정한 시간 이내에 Alive 메시지를 발송하지 않으면 접속을 강제로 종료합니다.

• Message sample :

  
  {
      "msgtype":"notify",
      "operation":"ras_alive",
      "channeltype":"system"
  }
  

• Client 에서 alive 처리는 다음의 WebSocket 클라이언트 샘플 소스 참고.

let ticker = 0;
setInterval(function() {
    ticker++;
    if (ticker % 30 === 7) {
        console.log('@ras-alive:' + ticker);
        var alive_session = {
            "msgtype": "notify",
            "operation": "ras_alive",
            "channeltype": "system"
        };
        socket.send(JSON.stringify(alive_session));
    }
}, 1000);

본 과정은 Dead connection 을 처리하기 위한 하나의 절차로 현재 버전에서는 하기의 조건으로 처리합니다.
• 서버 접속 종료 시간: 70 seconds
• 클라이언트 권장 주기: 30 ~ 60 seconds

Session 생성 요청 (request, create_session)

Session 생성을 요청합니다. Session id는 기본적으로 서버에서 생성하며, Session id 를 지정하면 지정된 이름으로 생성합니다.

• Default session id 의 message sample:

  
  {
      "msgtype":"request",
     "operation":"create_session",
     "channeltype":"webrtcaudio",
     "uuid":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
     "trxid":"K0000000:1501463079077:00002"
  }
  

• Specific session id 의 message sample:

  
  {
      "msgtype":"request",
      "operation":"create_session",
      "channeltype":"webrtcaudio",
      "sessionid":"abcd", 
      "uuid":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "trxid":"K0000000:1501463079077:00002"
  }
  

• Client 에서 상기 create_session까지의 일련의 과정은 WebSocket 클라이언트 샘플 소스 참고.

※ 클라이언트는 주기적으로 alive 메시지를 발송해야 접속을 유지할 수 있습니다.

Session 입장 요청 (request, join_session)

Session 입장을 요청합니다.
주의) 새로운 Client 는 초기 인증과정을 처리해야만 합니다.

① Request join 을 요청합니다.
• Message sample:

  
  {
      "msgtype":"request",
      "operation":"join_session",
      "channeltype":"webrtcaudio",
      "sessionid":"aaaa",
      "uuid":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "trxid":"K0000000:1501463079077:00002"
  }
  

② Request join 에 대한 Reply 처리가 됩니다.
• Message sample:

  
  {
      "msgtype":"reply",
      "operation":"join_session",
      "result_cd":200,
      "result_msg":"Success",
      "trxid":"K0000000:1501463079077:00002"
  }
  

③ 입장이 되면 해당 Channel 에 Notify join_session 이 발생합니다.
• Message sample:

  
  {
      "msgtype":"notify",
      "operation":"join_session",
      "sessionid":"aaaa",
      "channeltype":"webrtcaudio"
  }
  

Session 종료 요청 (request, destroy_session)

Session 종료을 요청합니다.

① Request destory 을 요청합니다.
• Message sample:

  
  {
      "msgtype":"request",
      "operation":"destroy_session",
      "channeltype":"webrtcaudio",
      "sessionid":"aaaa",
      "uuid":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "trxid":"K0000000:1501463079077:00003"
  }
  

② Request join 에 대한 Reply 처리가 됩니다.
• Message sample:

  
  {
      "msgtype":"reply",
      "operation":"destroy_session",
      "result_cd":200,
      "result_msg":"Success",
      "trxid":"K0000000:1501463079077:00003"
  }
  

③ 입장이되면 해당 Channel 에 Notify destroy_session 이 발생합니다.
• Message sample:

  
  {
      "msgtype":"notify",
      "operation":"destroy_session",
      "sessionid":"aaaa",
      "channeltype":"rtcaudio"
  }
  

Data 전송 (Data)

OTV WebApp Message 정의

기능	Message	발화패턴 예시
초기화면	webapp.home	처음으로, 초기화면
상담전화연결	webapp.call	주문전화, 상담전화
바로주문	webapp.order.now	바로주문, 주문해줘
상품검색	webapp.product.search	<상품명> 상품 찾아줘, <상품명> 상품 보여줘
상품추천	webapp.rec	추천상품, 상품추천해줘
다음동영상노출	webapp.vod.next	다음방송상품, 다음시간상품
TV편성표보기	webapp.vod.schedule	<채널명> 편성표
도움말	webapp.help	<채널명> 도움말, <채널명> 안내