@livuvo/live-sdk-base

Livuvo Base Live SDK

Introduction

Welcome to the documentation for the @livuvo/live-sdk-base library. This library only contains functionality for live service of Livuvo and you should implement UI on your own.

Installation

You can install this package using npm:

npm install @livuvo/live-sdk-base

or yarn:

yarn add @livuvo/live-sdk-base

React

Several hooks and components have been provided to facilitate data retrieval and display in your UI. You won't need to deal with the complexity of handling data fetching, remote WebSocket events, and more. To utilize these features, simply import the following hooks and components from the specified path:

import { Container, actions, useEvents, useStore } from "@livuvo/live-sdk-base/react";

Container

You should wrap this component around your entire live page. This component is in charge of fetching initial data, handling websocket events and making store ready for you to use.

Props type:

interface Props {
  userToken: GLiveUserToken;
  children?: ReactNode;
}

Example:

import { Container } from "@livuvo/live-sdk-base/react";

function YourLivePage() {
  return <Container userToken={userTokenObjectYouHaveGotFromYourBackend}>{/* your UI goes here */}</Container>;
}

useStore

This object is a zustand store which contains all state of live. you just need to use this to get data and show it in your UI. for example, to show chat messages, do this:

import { useStore } from "@livuvo/live-sdk-base/react";

function YourChatBox() {
  const messages = useStore((state) => state.messages);

  return; // render the messages
}

store contains all of this fields, you may not need to use all of them, only use what you need:

interface StoreType {
  connected: boolean; // websocket is connected or not
  live: GLive | null; // current live details
  userToken: null | GLiveUserToken; // the userToken object you have passed to Container component
  analytics: GLiveAnalytics; // live analytics information like: message count, concurrent viewers and ...

  messages: GLiveMessage[]; // array of messages
  chatLoading: boolean; // true when fetching messages
  chatPager: GPager | null; // messages pagination information

  productsLoading: boolean; // true when fetching products list from api
  productPager: GPager | null; // products pagination information
  products: GProduct[]; // array of products
}

useEvents

This hooks returns 3 methods for you:

import { useEvents } from "@livuvo/live-sdk-base/react";

function Test() {
  const liveEvents = useEvents();

  liveEvents.sendProductClick();
  liveEvents.sendLike();
  liveEvents.sendMessage({ text: "message", reply_to: GLiveMessage | null });
}

liveEvents.sendProductClick

Everywhere you render your product cards, you should fire this function on it's onclick. This function will send some events to Livuvo to calculate CTR of products.

function MyProductCard() {
  const liveEvents = useEvents();

  return <div onClick={liveEvents.sendProductClick}>{/* your UI */}</div>;
}

liveEvents.sendLike()

In your UI, you can implement a like button for live, and whenever someone clicked on it, call this function to track likes count of live.

function ChatBox() {
  const liveEvents = useEvents();

  return (
    <div>
      <LikeButton onClick={liveEvents.sendLike} />
    </div>
  );
}

liveEvents.sendMessage({ text: 'message', reply_to: GLiveMessage | null });

You should call this function for sending a chat message.

function ChatBox() {
  const liveEvents = useEvents();

  const handleSendMessage = () => {
    liveEvents.sendMessage({
      text: "message",
      reply_to: null,
    });
  };

  return (
    <div>
      <Input onSubmit={handleSendMessage} />
    </div>
  );
}

actions

import { actions } from "@livuvo/live-sdk-base/react";

type:

interface actions {
  loadMoreProducts(): void;

  loadMoreMessages(): void;
}

actions.loadMoreProducts

if user has scrolled products carousel and has reached to end of it, call this function to load more products.

import { actions, useStore } from "@livuvo/live-sdk-base/react";

function ProductsCarousel() {
  const products = useStore((state) => state.products);

  /**
   * you may want to show a loading when user has reached end and loadMoreProducts has been fired.
   * use productsLoading key in useStore.
   * Note: if products.length is 0 and productsLoading is true, that means it's intial request for loading products.
   */
  const productsLoading = useStore((state) => state.productsLoading);

  const onScrollReachedEnd = () => {
    actions.loadMoreProducts();
  };

  return (
    <div>
      {products.map(() => (
        <YourProductCard />
      ))}
    </div>
  );
}

actions.loadMoreMessages

if user has scrolled chat box and has reached to end of it, call this function to load more messages. this function is as same as actions.loadMoreProducts

Types

you can import all of below types from this path:

import { GLive, ... } from '@livuvo/live-sdk-base/types';

interface GMessaging {
  button?: {
    href: string;
    background: GColorRGBA;
    text: string;
    color: GColorRGBA;
  };

  invitation_message?: {
    text: string;
    color?: GColorRGBA;
    background?: GColorRGBA;
  };
}
enum GUserRoleEnum {
  Host = "HOST",
  Moderator = "MODERATOR",
  Admin = "ADMIN",
  Owner = "OWNER",
}
interface GUser {
  first_name: string;
  last_name: string;
  email: string;
  phone: string;
  username: string;
  image: string | null;
  slug: string;
}
type GSlug = string;
enum GLiveStreamStatus {
  Pending = "PENDING",
  Playing = "PLAYING",
  Paused = "PAUSED",
  Ended = "ENDED",
}
enum GLiveRecordStatus {
  Pending = "PENDING",
  Inprogress = "INPROGRESS",
  Done = "DONE",
}
interface GProduct {
  price: number | null;
  image: string;
  title: string;
  description: string;
  url: string;
  live_slug: string;
  space_slug: string;
  active: boolean;
  created_at: string;
  updated_at: string | null;
  is_deleted: boolean;
  slug: string;
  activated_at?: string;
}
enum GLiveStatus {
  Pending = "PENDING",
  Ready = "READY",
  Started = "STARTED",
  Ended = "ENDED",
}
interface GLiveMessage {
  avatar: string | null;
  created_at?: string;
  display_name: string;
  slug: string;
  live_slug: string;
  space_slug: string;
  text: string;
  user_id: string;
  reply_to: GLiveMessage | null;
  visible?: boolean;
}
interface GLivePermissions {
  can_activate_product: boolean;
  can_add_product: boolean;
  can_approve_live: boolean;
  can_delete: boolean;
  can_delete_product: boolean;
  can_edit_live: boolean;
  can_edit_members: boolean;
  can_edit_product: boolean;
  can_edit_settings: boolean;
  can_edit_start_time: boolean;
  can_end_live: boolean;
  can_pause_live: boolean;
  can_pin_message: boolean;
  can_resume_live: boolean;
  can_start_live: boolean;
}
interface GLive {
  title: string;
  caption: string;
  pin_message: {
    avatar: string | null;
    display_name: string;
    text: string;
    user_id: GSlug;
  } | null;
  slug: string;
  cover: string;
  status: GLiveStatus;
  approval: "PENDING" | "APPROVED" | "REJECTED";
  stream_status: GLiveStreamStatus;
  start_time: string;
  started_at: string | null;
  ended_at: string;
  created_by: string;
  space: string;
  timezone: string;
  messaging: GMessaging;
  live_chat: boolean;
  viewer_count: boolean;
  created_at: string;
  recorded_url: string;
  owner: GUser;
  hosts: GUser[];
  user_role: GUserRoleEnum;
  recorded: GLiveRecordStatus;
  moderators: GUser[];
  permissions: GLivePermissions;
  settings: {
    chat_enabled: boolean;
    record: boolean;
    viewer_count_enabled: boolean;
  };
}
interface GLiveAnalytics {
  conc_count: number;
  conc_unique_count: number;
  like_count: number;
  message_count: number;
  product_click_count: number;
}
interface GLiveUserToken {
  display_name: string;
  is_blocked: boolean;
  scope: "live";
  session: string;
  slug: GSlug;
  space_slug: GSlug;
  token: string;
  user_id: string;
}

Backend Endpoint description

The endpoint URL for fetching userToken is: https://neo.livuvo.com/authnz/api/v1/user-token/[SPACE-SLUG]/live/[LIVE-SLUG]/

It's important to note that this endpoint should be accessed from the backend due to security considerations. This is because you need to provide a confidential Authorization token (Authorization header) as part of the request. To obtain an API token, follow these steps:

1. Visit app.livuvo.com.
2. Navigate to the space settings page.
3. In the "API Tokens" section at the bottom, you can generate a new API token.
4. Set obtained api token as Authorization header.

When making a request to the endpoint, include the following object in the request body: This object should be sent as part of the POST request to the specified URL.

{
  "user_id": "USER_ID",
  "display_name": "DISPLAY_NAME",
  "chat": "rw"
}

Please ensure that you handle this sensitive information securely and follow best practices for API token management.