FlipFlop SDK for Javascript

Live Commerce Javascript SDK

설치

$ npm i -s flipflop-sdk-javascript

사용법

SDK 초기화

1. 라이브러리 가져오기

import { FlipFlop } from 'flipflop-sdk-javascript/dist/flipflop';

2. 라이브러리 초기화

• https://flipflop.tv 에서 발급받은 appKey 와 appSecret을 입력해주세요

// Initialize SDK
await FlipFlop.initialize(appKey: APP_KEY, appSecret: APP_SECRET)

3. 라이브러리 인증

• 중복되지 않은 userID를 입력하세요.
  • 숫자 혹은 영문자만 입력 가능합니다. (a-zA-Z0-9)
  • 특수문자를 사용할 수 없습니다.
• userName과 avatarProfileURL은 선택사항입니다.
• 인증에 성공하게 되면 사용할 수 있는 라이브러리 인스턴스를 반환합니다.

const sdk = await FlipFlop.authentication(userID, userName, avatarProfileURL)

4. 유저 정보 업데이트

• 라이브러리 인증 단계에서 설정한 유저 이름을 수정

sdk.updateUserInfo(userName: "Updated User");

라이브 방송 하기

1. 라이브를 하기 위한 instance 생성

// 라이브 방송 객체 생성
const streamer = sdk.getStreamer()

2. 라이브 이벤트 콜백 등록

• 라이브를 할 떄 사용할 이벤트 콜백을 등록

// 라이브 방송 이벤트 콜백 등록
const StreamerDelegate = {
    // 방송 준비 이벤트
    onPrepare: () => {},
    // 방송 시작 이벤트
    onStart: (streamName) => {},
    // 방송 중지 이벤트
    onStop : () => {},
    // 방송 종료 이벤트
    onCompleted: () => {},
    // 방송 채팅 메시지 가저오는 이벤트 콜백
    onChatMessageReceived: (message) => {},
    // 방송 에러 이벤트
    onError: (error) => {},
    // 방송 채팅 연결 성공 이벤트
    onConnectSuccess: () => {},
    // 방송 채팅 연결 실패 이벤트
    onConnectFailure: () => {},
    // 방송 채팅 끊기 이벤트 (player.disconnect)
    onDisconnect: () => {}
}

streamer.delegate = StreamerDelegate

3. 라이브 방송송출

// 카메라프리뷰 및 마이크 시작 및 방송 준비
streamer.prepare(previewVideo)

// 방송을 시작합니다. 방송 타이틀과 내용 입력. onPrepared 이후에 호출해야 함
streamer.start(title: TITLE, content: CONTENT)

4. 라이브 방송송출 중단

송출 종료 후, keepAlive = true를 통해 라이브를 지정된 시간(10분)이 지나야 라이브가 끝난 것으로 처리되게 할 수 있다. 기본값: false

// 방송을 종료합니다.
// keepAlive = false (기본값): 바로 송출 종료
// keepAlive = true: 10분 후 라이브 종료
streamer.stop(keepAlive)

// 라이브 방송 객체 메모리 해제
streamer.reset()

5. 채팅 메시지

• 메시지 보내기

streamer.sendMessage(text: "Blar Blar Blar....", customType?)

• 메시지 받기

StreamerDelegate의 onChatMessgeReceived를 통해 들어온 메시지를 처리한다

방송 보기

1. 방송을 보기 위한 instance 생성

// 플레이어 객체 생성
const player = sdk.getPlayer(videoKey)

2. 방송보기 이벤트 콜백 등록

• 방송을 볼 떄 사용할 이벤트 콜백을 등록

 const PlayerDelegate = {
    // 방송 준비 이벤트
    onPrepare: (player) => {},
    // 방송 시작 이벤트
    onStart: (player) => {},
    // 방송 종료 이벤트
    onStop: () => {},
    // 방송 에러 이벤트
    onError: (error) => {},
    // 방송 채팅 메시지 수신시 이벤트
    onChatReceived: (message) => {},
    // 방송 채팅 메시지 가저오는 이벤트 콜백
    onChatMessageReceived: (messages) => {},
    // 방송 채팅 연결 성공 이벤트
    onConnectSuccess: () => {},
    // 방송 채팅 연결 실패 이벤트
    onConnectFailure: () => {},
    // 방송 채팅 끊기 이벤트 (player.disconnect)
    onDisconnect: () => {}
}

// 플레이어 준비
player.prepare(PlayerDelegate)

3. 방송보기 시작

// 플레이어 시작. onPrepare 이후 호출
// isObserver: 스트리머 혹은 어드민 계정일 경우 true (default: false)
player.start(isObserver)

4. 방송보기 중지

// 플레이어 중지
player.stop()

// 플레이어 객체 메모리 해제
player.reset()

5. 채팅 메시지

• 메시지 보내기

// 채팅 보내기
player.sendMessage(text: "Blar Blar Blar....", customType?)

• 메시지 받기

PlayerDelegate의 onChatMessgeReceived를 통해 들어온 메시지를 처리한다

• 메시지 가져오기

// 방송 진입 시점 이전 채팅 히스토리 가져오기: ChatHistory[]
const histories = await player.getPastMessages()

// 방송 채팅 메시지 가져오기
const messages = await player.getChatMessages(option)

채팅 메시지 가져오기 옵션 (getChatMessages option)

| params | value | default value | description | |:--------------:|:--------------------:|:------------------------------------:|:----------------:| | custom_types | string OR string[] | 모든 타입 | player.sendMessage 함수를 통해 사용자가 임의로 넣은 타입 | | message_types | string OR string[] | 모든 타입 | MESSAGE, DM, JOIN, LEAVE, COMMAND, ADMIN | | timestamp | number |timestamp, message_id 둘다 비어 있으면 비디오 시작시간 기준| messaeg id 혹은 timestamp를 기준으로 메시지를 가져온다 (둘 중 하나만 사용)| | message_id | number |timestamp, message_id 둘다 비어 있으면 비디오 시작시간 기준| messaeg id 혹은 timestamp를 기준으로 메시지를 가져온다 (둘 중 하나만 사용) | | prev_size | number | 20 | timestamp 혹은 message id 기준으로 이전에 가져올 메시지 수 | next_size | number | 20 | timestamp 혹은 message id 기준으로 이후에 가져올 메시지 수 | | is_inclusive | boolean | false | 기준 시점을 포함해서 메시지를 가져올지 여부 |

message_types 설명

| message_type | custom_type | description | |:--------------:|:----------------:|:----------------:| | MESSAGE | - | 일반 메시지 | | DM | - | 귓속말 메시지 | | JOIN | - | 사용자 채팅방 진입 메시지 | | LEAVE | - | 사용자 채팅방 이탈 메시지 | | COMMAND | - | 클라이언트가 보내는 명령 메시지 (공지변경, 대표상품변경 등) | | ADMIN | UPDATE | 방송 정보 업데이트에 관한 메시지 | | ADMIN | INACTIVE | 방송 송출 일시중단 | | ADMIN | ACTIVE | 방송 송출 재개 | | ADMIN | CLOSE | 방송 종료 | | ADMIN | DISCONNECT | 방송 강제종료 |

비디오 리스트 가져오기

비디오 리스트로더를 이용하여 next 함수 호출시 비디오 리스트를 가져옴 더 이상 가져올 비디오가 없으면 빈 배열이 내려옴

const loader = sdk.getVideoListLoader();
const videos = await loader.next();

비디오 화상회의

Conference 객체를 안에서 사용하는 기능은 크게 Video Room 안에서 사용하는 기능과 Video Room 밖에서 사용하는 기능으로 나뉩니다.

Video Room 밖에서 사용하는 대표적인 기능으로는 비디오 룸 생성/삭제, 비디오 리스트 조회, 비디오 룸 비밀번호 체크 등이 있습니다. 위의 기능은 일반적으로는 비디오 룸 밖에서 사용하지만 필요하다면 비디오 룸 안에서도 사용 가능합니다.

반면, Video Room 안에서 사용하는 기능은 반드시 Conference 객체안의 prepare함수와 start함수가 성공적으로 실행된 후에 사용 가능하여야 합니다. Video Room 안에서 사용하는 대표적인 기능로는 참여자 강퇴, 음소거, 카메라on/off 등이 있습니다.

위의 상황에 유의하여 화상회의 SDK를 사용하시기 바랍니다.

Conference 객체 화상회의 밖에서 사용하는 기능 명세서

| 필드명 | 파라미터 | 리턴 | 설명 | | :---------: | :---------: | :---------: | :---------: | | getRooms(option) | option: Option | roomList: RoomInfo[] | 회의실 리스트 조회 | | createRoom(title, pin) | title: stringpin: string | room: RoomInfo | 회의실 생성 | | deleteRoom(roomId) | roomId: string | room: RoomInfo | 회의실 삭제 | | checkPin(roomId, pin) | roomId: stringpin: string | isValid: boolean | 회의실 입장 전 비밀번호 확인 |

Conference 객체 화상회의 안에서 사용하는 기능 명세서

| 필드명 | 파라미터 | 콜백 | 설명 | | :---------: | :---------: | :---------: | :---------: | | prepare(request) | request: PrepareRequest | onPrepare() | Conference에서 사용할 콜백 객체 등록,변수 초기화 | | start(videoEl) | videoEl: HTMLVideoElement | onStart(stream) | 회의실 참석videoEl: 내 비디오를 표시할 Video Elementstream: 내 비디오 스트림 | | stop() | - | onStop() | 회의실 나가기 | | attachMediaStream(videoEl,stream) | videoEl: HTMLVideoElementstream: MediaObject | - | 비디오 태그에 미디어 스트림 소스 연결 | | mute(on) | on: boolean | - | 내 오디오 송출 끄기/켜기 | | camera(on) | on: boolean | - | 내 비디오 송출 끄기/켜기| | getParticipants() | participantList: ParticipantInfo[] | - | 회의실 참여자 리스트 조회 |

1. 화상회의 객체 생성

우선, 화상회의를 시작하기 앞서 SDK에서 Conference 인스턴스를 생성합니다. Conference 객체는 비디오룸 생성, 삭제 등 화상회의 시작할 때 필요한 기능들을 담고 있습니다.

// 화상회의 객체 생성
const conference = sdk.getConference();

2. 비디오 룸 생성

Conference 객체를 생성했으면, 화상회의를 진행하기 위한 비디오 룸을 생성해야 합니다.

/**
 * this.conference.createRoom
 * @param {string} id 
 * @param {string} pin
 */
conference.createRoom(title, pin).then(() => {
    // 성공시 로직
  }).catch(() => {
    // 실패시 로직
  })

3. 비디오 룸 리스트 조회

비디오 룸이 제대로 생성이 되었다면 비디오 룸 리스트 조회 API를 통해 비디오 룸을 조회할 수 있습니다.

conference.getRooms().then((roomList) => {
    // 성공시 로직
  }).catch(() => {
    // 실패시 로직
  })

4. 비디오 룸 입장

비디오룸을 입장하기 위해서는 prepare함수와 start함수를 사용해야 합니다. prepare함수는 비디오 룸에서 사용하는 화상회의 콜백을 등록하고 비디오 오디오 설정들을 초기화해주며, 클라이언트에서 사용하는 브라우저의 지원여부를 체크합니다. start함수는 비디오 룸에 소켓으로 비디오 룸에 접송하여 자신의 비디오/오디오 리소스를 매개변수로 입력받은 비디오 Element에 송출하는 기능을 제공합니다.

 const ConferenceDelegate = {
    // 회의실 준비 이벤트
    onPrepare: () => {},
    // 회의실 참석 시작 이벤트
    onStart: (stream) => {},
    // 회의실 나가기 이벤트
    onStop: () => {},
    // 야누스 Room 소켓 접속 성공
    onConnect: () => {},
    // 야누스 Room 소켓 접속 실패
    onDisconnect: () => {},
    // 누군가 회의실에 비디오 송출을 하거나 끊을 때 이벤트
    onFeedsReceived: (feeds: MediaObject[]) => {},
    // 사용자 커스텀 이벤트 
    onEvent: (key) => {
      switch(key) {
        case "kicked":
          // 강퇴 이벤트
        case "destroyed":
          // 회의룸 종료 이벤트
      },
    }
}

const request = {
  roomId: "string",
  pin: "string",
  delegate: ConferenceDelegate,
  options: {
    useVideo: true, // 입장시 비디오 활성화 여부
    useAudio: true // 입장시 오디오 활성화 여부
  }
}

conference.prepare(request).then(async () => {
  const videoEl = document.getElementById("myvideo");
  const room = await conference.start(videoEl);
})

화상회의 Callback 명세서

• onPrepare() 브라우저가 WebRtc를 지원하는지 체크, 화상회의 기본 설정 초기화, 콜백 등록합니다.
• onStart(stream) 플러그인 등록, 회의실에 참가한 비디오 정보들 이용 가능, API 사용 가능
• onStop() 화상회의 룸을 퇴장할 떄 이벤트이며, Conference 객체의 stop() 함수 실행시 콜백으로 실행됩니다.
• onConnected() 화상회의 룸에 소켓 연결 성공시 발생하는 이벤트입니다.
• onDisconnected() 화상회의 룸에 소켓 연결 해제시 발생하는 이벤트입니다.
• onFeedsReceived(feeds) 화상회의 룸에 비디오 송출이 들어오거나 비디오 송출을 중지하는 사람이 있으면 발생하는 이벤트입니다.
• onEvent(key, msg) 강퇴 및 회의실 강제 삭제 등 사용자가 커스텀할 수 있는 이벤트 콜백을입니다.

License

MIT License

© 2014 Jocoos. All rights reserved.