SDK for templates

JavaScript SDK for template development

Usage notes

Please review the terms of service again

The OneComme Terms of Service also applies to connected applications and services

About credit notices

When using an application or service that relies on the HTTP API, a credit notice is required if you're using it for free

When distributing an application, be sure to include a note about the credit notice

About accessing from an external IP or domain

For security reasons, OneComme's API restricts access from anything other than a local IP

To access the API from an external IP or domain, you need to register the hostnames you want to allow under "Settings > API tab" (Settings page)

How to use

npm install @onecomme.com/onesdk -S

Alternatively, use preset/__origin/js/onesdk.js found in the templates folder
(also accessible at http://localhost:11180/templates/preset/__origin/js/onesdk.js)

API

ready():Promise< void >

Resolves the Promise once the page has finished loading
If loading is already complete, it resolves immediately

setup(config: Partial< OneSDKConfig >): void

Performs the initial configuration of the SDK
Calling this function is required

export type Protocol = 'ws' | 'local'  
export interface OneSDKConfig {  
  protocol: Protocol // Connection protocol (Default: 'local')  
  port: number // Port (Default: 11180)  
  host: string // Hostname (Default: 'localhost')  
  pathname: string // API pathname (Default: '')  
  mode: 'all' | 'diff' // Comment retrieval mode (Default: 'all') all=retrieves all recently fetched comments every time (excluding deleted ones) diff=always retrieves only the latest  
  disabledDelay: boolean // Set comment retrieval delay to 0 (Default: false)  
  intervalTime: number // Comment update interval (Default: 5000)  
  maxQueueInterval: number // Interval used when there are consecutive comments (Default: 150)  
  reconnectInterval: number // Reconnection interval after disconnection (Default: 5000)  
  commentLimit: number // Maximum number of comments to keep in the SDK (Default: 100)  
  includes: string[] | null // Streaming services to retrieve (Default: null)  
  excludes: string[] | null // Streaming services to exclude (Default: null)  
  includeIds: string[] | null // User IDs to receive (Default: null)  
  excludeIds: string[] | null // User IDs to exclude (Default: null)  
  includeNames: string[] | null // Stream names to retrieve (Default: null)  
  excludeNames: string[] | null // Stream names to retrieve (Default: null)  
  lifeTime: number // Comment retention time (Default: Infinity)  
  permissions: SendType[] | null // API Permission  
}

subscribe(subscriber: Subscriber): number

Subscribes to events triggered by changes in OneComme
Returns the subscription ID needed to unsubscribe

export type Subscriber = {  
  action: T // Action name specified in permissions  
  callback: (response: PublishActions[T]) => void  
}

unsubscribe(subscriberId: number): void

Stops the event subscription associated with the given subscription ID

reset():void

Resets data such as retrieved comments

getStyleVariable< T = any >(name: string, defaultValue: T, parser: (val:string) => T): T

A function that retrieves the value of a CSS variable defined on :root

getCommentStyle(comment: Comment): {[key: string]: string}

Returns color information for Super Chats or memberships, such as on YouTube, based on the comment

export interface Comment {  
  id: string  
  service: ServiceType // Identifier of the streaming platform the comment was received from  
  name: string  
  url: string  
  color: RGBColor // Color information configured for the stream {r,g,b}  
  meta?: BaseCommentMeta  
  data: CommentData  
}  
export interface BaseCommentMeta {  
  no?: number // Comment number  
  tc?: number // Cumulative comment count  
  lc?: number // Comment count  
  interval?: number // Comment interval  
  free?: boolean // Whether it's a free gift  
}  
export interface CommentData {  
  id: string  
  userId: string  
  liveId: string  
  name: string  
  screenName?: string  
  isOwner: boolean  
  isSupporter?: boolean  
  displayName?: string  
  nickname?: string  
  hasGift: boolean  
  autoModerated?: boolean  
  profileImage: string  
  originalProfileImage?: string  
  badges: BaseBadge[]  
  timestamp: string  
  comment: string  
  speechText?: string  
  isFirstTime?: boolean  
  isRepeater?: boolean  
  commentVisible?: boolean  
  meta?: CommentMeta  
}  
export interface BaseBadge {  
  url: string  
  label: string  
  type?: string  
}  
export interface CommentMeta {  
  hasNickname?: boolean  
  hasMemo?: boolean  
  anonymity?: boolean  
  label?: string  
  type?: 'system'  
}

checkLicensed(): Promise< boolean >

Returns a flag indicating whether the PRO version is being used

connect(): Promise< void >

Connects to the OneComme API server
Calling this function is required

getInfo(): Promise< AppInfo >

Returns basic information about the OneComme app

export interface AppInfo {  
  platform: 'win' | 'mac'  
  version: string  
  port: number  
  licensed: boolean  
  templatePath: string  
  templateUrl: string  
}

getOrders(): Promise< OrderItem[] >

Returns the list of queue entries for the viewer participation system

export interface OrderItem {  
  id: string // userid  
  commentId: string  
  service: ServiceType  
  serviceName: string  
  username: string  
  profileImage: string  
  timestamp: string  
  comment: string  
  count: number  
  completed: boolean  
  playing: boolean  
  anonymity: boolean  
  userData?: UserNameData  
  totalCount?: number  
  lastCompletedAt?: string  
}

cancelOrder(orderId: string): Promise< OrderItem[] >

Cancels a queue entry based on the participation ID

Returns the updated queue list after cancellation

completeOrder(orderId: string): Promise< OrderItem[] >

Completes a queue entry based on the participation ID

Returns the updated queue list after completion

getSetList(): Promise< SetListAPIResponse >

[Provisional implementation] Returns the setlist

export interface SetListAPIResponse {  
  id: number  
  name: string  
  items: MusicData[]  
  completed: MusicData[]  
}  
export interface MusicData {  
  id: number  
  box: number  
  name: string  
  link: string  
  tags: string[]  
  memo: string  
}

Permission

To receive various data from the SDK, you must explicitly specify which data to receive

Multiple values can be specified as an array in config's permissions

Anything specified in permissions becomes available as an event type receivable via subscribe