Shoplive Web Player SDK Integration Guide

The Shoplive Web Player SDK connects a live broadcast player to your web page with a single script tag. There is no package to install and no build tooling to configure.
Embed the player wherever you want it, open a broadcast with a single link, or show a preview on another page — pick only the approaches you need.

Start now →

What you need

What do you want to build?

Finish Mission 1 and a broadcast is on screen. Missions 2–6 are independent of each other, so pick only what you need, in any order — this is not a list you have to complete.

What each element on the player screen is called is collected in the screen glossary — come back to it when you are reading a mission and cannot remember what removeBanner removes.

The shortest path to a player on screen. For the details and options, start from Mission 1 below.

<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });
</script>

<div id="shoplive-player"></div>
<script>
  cloud.shoplive.setPlayer("shoplive-player", { campaignKey: "YOUR_CAMPAIGN_KEY" });
</script>

cloud.shoplive is a global object the SDK sets up for you. Once the script above loads, functions such as initPlugin and setPlayer are attached to window.cloud.shoplive. That means you can call cloud.shoplive.… from any script with no import and no bundler configuration — as long as the call comes after the SDK script tag. The full set of functions is in the function index.

Next stepScreen glossary · Start with Mission 1 →

The names for each element on the player screen. The missions, the event dictionary and the command dictionary all use these same terms and the same numbers. When you cannot remember what removeBanner actually removes, come back to this table.

The player screen

Where the web differs from mobile

Most of the UI inside the player is switched on and off through campaign settings in Shoplive Admin. What you can change from code is collected in Mission 1 · what to show on screen.

Previous ← QuickstartNext → Mission 1 · Display the broadcast

There are three approaches. Pick just one — all three run on the same initPlugin().

Approach AEmbed the player directly

Use this when you can build the page yourself. Put a container where you want the player and call setPlayer.

<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });
</script>

<div id="shoplive-player"></div>
<script>
  cloud.shoplive.setPlayer("shoplive-player", {
    campaignKey: "YOUR_CAMPAIGN_KEY"
  });
</script>

The player fills the container div, so you set the container size and position with your own page CSS. When a broadcast ends and turns CLOSED you can leave campaignKey exactly as it is — the same key plays the replay.

What to show on screen optional

cloud.shoplive.setPlayer("shoplive-player", {
  campaignKey: "YOUR_CAMPAIGN_KEY",
  ui: { viewerCount: true, likeCount: true, backButton: true, shareButton: true }
});

The inside of the player — chat, the product list and so on — is decided by your account settings and theme. If you need to change anything beyond these four, contact your Shoplive representative.

The URL the share button sends optional

If you turned the share button on, you can set the address that gets shared with shareUrl on initPlugin(). Leave it out and the current page address is used. To change the share behavior itself, and for how the URL is assembled, see Mission 3.

cloud.shoplive.initPlugin({
  accessKey: 'YOUR_ACCESS_KEY',
  shareUrl: 'https://my-shop.com/live'   // optional — defaults to the current page
});

Always full screen optional

cloud.shoplive.setPlayer("shoplive-player", {
  campaignKey: "YOUR_CAMPAIGN_KEY",
  isFullScreen: true
});

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, viewport-fit=cover, shrink-to-fit=no">

Other options optional

Values you only need in particular situations. Normally you can leave them unset.

Re-rendering and cleaning up

Calling setPlayer again on the same container tears the existing player down and builds a new one. You do not need to call destroy first when swapping in a different broadcast.

The opposite case is different: when the container itself disappears from the page (a component unmounting in an SPA, for example) the SDK cannot detect it and the player stays alive internally. Call destroyPlayer before removing the container.

cloud.shoplive.destroyPlayer("shoplive-player");

Approach BOpen directly via link

When building a new page is impractical, call the shoplive.show page that Shoplive provides using URL parameters alone — no page of your own required. Note that the SDK runs only inside the shoplive.show page and is not loaded on the page that opens the link, so you cannot call initPlugin(). If you need user interaction handling (Mission 3), use Approach A or C.

https://www.shoplive.show/v1/player.html?ak={access_key}&ck={campaign_key}&tk={user_info}

The shareUrl option that sets the page URL sent when the share button is tapped (see Approach A) only takes effect through a direct initPlugin() call, so it is unavailable in Approach B. There, your only option is shareButton=0 to hide the share button entirely.

Approach CLive page template — player and broadcast list in one go

Use this when you need a whole live corner page rather than a single player. Call setOverall on one empty div and the Shoplive template draws a featured broadcast (live now, or the most recent one) plus a broadcast list inside it. You do not have to decide in code which broadcast to show, which makes it a good fit for a permanent corner where the broadcast keeps changing.

<div id="shoplive-overall-area"></div>
<script>
  cloud.shoplive.setOverall('shoplive-overall-area');
</script>

Tapping a broadcast in the list opens a modal player automatically. To handle that yourself, register ON_CLICK_CAMPAIGN_LIST_ITEM (Mission 3).

Showing only one area optional

To place the two areas far apart on the page, create two divs and call one with featuredOnly and the other with campaignListsOnly.

Shaping the list optional

cloud.shoplive.setOverall('shoplive-overall-area', {
  campaignListsOnly: true,
  campaignStatus: ['ONAIR', 'CLOSED'],   // sorted in this order
  tags: ['sale', 'new'],
  tagSearchOperator: 'OR',               // 'OR' any match · 'AND' all must match
  displayTags: ['sale', 'new', 'best'],  // shown as filter tabs above the list
  campaignList: { layout: 'HORIZONTAL' } // 'GRID' (default) | 'HORIZONTAL'
});

cloud.shoplive.setOverall('shoplive-overall-area', {
  sectionTitles: {
    onair:  'Live now',
    ready:  'Coming up',
    closed: 'Past broadcasts',
    all:    'All broadcasts'
  }
});

Cleaning up

Call destroyOverall when leaving the page in an SPA. Passing true as the second argument also tears down any player still inside it.

cloud.shoplive.destroyOverall('shoplive-overall-area', true);

Opening in a modal optional

Instead of reserving an area on the page, open the broadcast in a modal over the screen when a button is tapped. Use it to launch a broadcast straight from a banner or button.

<button id="open-live">Watch live</button>
<script>
  document.getElementById('open-live').addEventListener('click', function () {
    cloud.shoplive.showFeaturedPlayerModal({ campaignKey: 'YOUR_CAMPAIGN_KEY' });
  });

  // close it from code
  // cloud.shoplive.dismissLayerModalPlayer();
</script>

Verify completion

• (Approach A) The player renders in the div you specified, and when the broadcast is ONAIR it attempts autoplay (browser autoplay policies may block it)
• (Approach B) The player opens from the URL alone, with no page of your own
• (Approach C) The featured broadcast and the broadcast list are drawn inside the div you specified, and tapping a broadcast in the list opens a modal
• If you turned the share button on, tapping it shares shareUrl when you set one, and the current page when you did not

Previous ← Screen glossaryNext → Mission 2 · Connect user info

Step 1 · Choose by login state — recommended setup

Step 2 · Call using your chosen method

If you already know the user at initPlugin() time, include it in that call. If login status is settled later (an SPA, for example), call setUserObject() / setUserJWT() afterwards instead. With simple auth every field but userId is optional; JWT has its own required fields (see Step 5). For guests, call neither.

// Simple auth — only userId is required, the rest are optional
const userObject = {
  userId: "",     // required — the logged-in user's unique ID. Empty means guest
  userName: "",   // optional — the name shown in chat. If omitted, the campaign settings decide whether to prompt or generate one. Banned words are shown replaced with *
  gender: "",     // optional — "m" | "f" | empty if unset
  age: "",        // optional — grouped into 5-year buckets in the statistics
  userScore: "",  // optional — integer from -100 to 100. Usable as a criterion for things like prize-draw eligibility
  userType: "",   // optional — referenced when an Entry Type restriction is configured
  profile: "",    // optional — profile image URL in the chat list, 64x64px recommended
  custom: "",     // optional — free-form data, up to 1KB
  canBid: true    // optional — auction bidding eligibility (Appendix A · auctions)
};

// Option 1 — include it in the initPlugin() call
cloud.shoplive.initPlugin({ accessKey: "YOUR_ACCESS_KEY", userObject });

// Option 2 — call separately after initPlugin() (when login info arrives later)
cloud.shoplive.initPlugin({ accessKey: "YOUR_ACCESS_KEY" });
cloud.shoplive.setUserObject(userObject);


// JWT auth works the same way — pass the token you build in Step 5
cloud.shoplive.initPlugin({ accessKey: "YOUR_ACCESS_KEY", userJWT: "USER_JWT" });
// or
cloud.shoplive.setUserJWT("USER_JWT");


// Log out · reset user info — clears the user info you set and returns to guest
cloud.shoplive.logout();
// Or set what you passed back to null: cloud.shoplive.setUserObject(null) / cloud.shoplive.setUserJWT(null)

// Simple auth
https://www.shoplive.show/v1/player.html?ak=YOUR_ACCESS_KEY&ck=YOUR_CAMPAIGN_KEY&tk=encodeURIComponent(JSON.stringify(userObject))

// JWT
https://www.shoplive.show/v1/player.html?ak=YOUR_ACCESS_KEY&ck=YOUR_CAMPAIGN_KEY&tk=USER_JWT

https://www.shoplive.show/v1/player.html?ak=YOUR_ACCESS_KEY&ck=YOUR_CAMPAIGN_KEY&userId=MEMBER_ID&userName=NICKNAME

Step 3 · If you use a store platform — auto-link optional

For stores built on Cafe24, WISA, Godomall or Shopify, you can hand initPlugin() nothing but platform and let the SDK read the store's login state instead of calling setUserObject() yourself. This replaces Step 2; it is not something you add on top of it.

In every case it is best to put this in a shared layout (the header area every page includes) so login state is picked up no matter which page the viewer lands on.

<!-- 1. Load the SDK -->
<script src="https://static.shoplive.cloud/shoplive.js"></script>

<!-- A. Cafe24 — add this only if your skin has no login-state module.
       Cafe24 replaces {$id} {$name} with the logged-in member's id and name.
       Rendering this module creates .xans-member-var-id / .xans-member-var-name,
       and the SDK reads those two classes -->
<div module="Layout_stateLogon" style="display:none;">{$id} {$name}</div>

<!-- B. WISA · Godomall · Shopify — output member info under these ids.
       Replace the braces with the member variables your store solution provides
         · Godomall : {=gSess.memId} / {=gSess.memNm}
         · WISA     : {{$회원아이디}} / {{$회원명}}
       When logged out the values are empty, so the viewer is treated as a guest -->
<div style="display:none;">
  <span id="cloud-shoplive-user-id">MEMBER_ID</span>
  <span id="cloud-shoplive-user-name">NICKNAME</span>
</div>

<script>
  // 2. Pass only platform — do not call setUserObject
  cloud.shoplive.initPlugin({
    accessKey: 'YOUR_ACCESS_KEY',
    platform: 'CAFE24'      // 'CAFE24' | 'WISA' | 'GODOMALL' | 'SHOPIFY'
  });
</script>

To check that it worked. Enter a broadcast while logged in and look at the name shown in chat. On Cafe24, if the member-info area (.xans-member-var-id · .xans-member-var-name) cannot be found, the console logs Failed - Get Cafe24 account; the other platforms simply stay on guest when the elements are missing. If auto-link is awkward for you, just call setUserObject() directly as in Step 2.

For where to put the code in each shop admin, see Appendix G · Where to install on each shop platform.

Step 4 · Hash the ID — avoid exposing the raw member ID

If you would rather not pass your internal member ID in the clear, hash it on your server and use the result as userId. Unlike masking, Shoplive cannot recover the original ID, while you can recompute the same value with your own hashing (same algorithm and salt) and map it back to the original user. Just be consistent so the same user always produces the same value — statistics and return-visit identification depend on it.

// Node.js — hash on your server (always the same salt and algorithm)
const crypto = require('crypto');

function hashUserId(raw) {
  return crypto.createHash('sha256')
    .update(raw + 'YOUR_SALT')
    .digest('hex');
}

const userId = hashUserId('MEMBER_ID');   // use it as userObject.userId or as the JWT's userId

Step 5 · Create the JWT for JWT auth (your backend)

The JWT for JWT auth is signed by your backend with the Secret Key that Shoplive issues. The page only receives the JWT from your backend and passes it to initPlugin({ userJWT }) or setUserJWT() (Approach B: the tk parameter).

1. Get the Secret Key from your Shoplive contact. It's a base64-encoded string
2. Build the payload below from the logged-in user and sign it with HS256
3. Issue a new JWT every time the page asks (right before each setUserJWT() call). Don't store a JWT in the browser and reuse it

Signing

Signing examples. Both produce the same token — just note that the Secret Key is a base64 string, and whether you pass it as-is or decode it first depends on the library.

// Java — jjwt. signWith decodes the base64 string for you
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import java.util.Date;

String base64EncodedSecretKey = "YOUR_BASE64_SECRET_KEY";   // from your Shoplive representative
long expiration = System.currentTimeMillis() + 12 * 60 * 60 * 1000L;   // 12 hours

String jwt = Jwts.builder()
    .signWith(SignatureAlgorithm.HS256, base64EncodedSecretKey)
    .setExpiration(new Date(expiration))
    .setIssuedAt(new Date())
    .claim("userId", "MEMBER_ID")     // required
    .claim("name", "NICKNAME")        // optional — chat display name
    .claim("userScore", 10)           // optional
    .claim("userType", "VIP")         // optional
    .compact();

// Node.js — jsonwebtoken. You must decode the secretKey yourself
const jwt = require('jsonwebtoken');

const base64EncodedSecretKey = 'YOUR_BASE64_SECRET_KEY';   // from your Shoplive representative
const secret = Buffer.from(base64EncodedSecretKey, 'base64');   // ← decoding required

const token = jwt.sign(
  {
    userId: 'MEMBER_ID',   // required
    name: 'NICKNAME',      // optional — chat display name
    userScore: 10,         // optional
    userType: 'VIP'        // optional
  },
  secret,
  { algorithm: 'HS256', expiresIn: '12h' }
);

If you need to tell guests apart — receiving the guest uid optional

For guest viewers you pass no user info for, the player issues an arbitrary identifier, uid. If your side needs that value too — to group coupon issues by a logged-out viewer, or to reconcile your own logs with Shoplive statistics — register ON_UID_ISSUED in messageCallback. It fires every time the player connects to the server.

const messageCallback = {
  ON_UID_ISSUED: function (payload) {
    // payload.uid — the guest identifier the player issued · payload.campaignKey — which broadcast
    const stored = localStorage.getItem('shoplive_uid');
    if (stored !== payload.uid) {
      localStorage.setItem('shoplive_uid', payload.uid);
    }
  }
};
cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY', messageCallback });

Verify completion

• After logging in, the name you set (the member's name) appears when a chat message is sent
• (If you configured an entry restriction) only users matching the userScore / userType criteria are admitted
• After you reset the user info with cloud.shoplive.logout(), viewing continues as a guest

Previous ← Mission 1 · Display the broadcastNext → Mission 3 · Handle user interactions

Interactions that need your own business logic — coupons, products, login — mostly arrive through messageCallback. This step is the heart of a real integration.

1. Register a function per action name on messageCallback when calling initPlugin().
2. Once registered, it is called automatically every time that action occurs.
3. (Optional) Update the player UI from inside the callback with getPlayer().

const messageCallback = {
  DOWNLOAD_COUPON: function (payload) {
    console.log('Coupon tapped. coupon code: ' + payload.coupon);
    fetch('YOUR_COUPON_API')
      .then(function (res) { return res.json(); })
      .then(function (res) {
        if (res.success) {
          alert('Coupon downloaded.');
          // The player may have closed while we waited, so look it up here (Mission 5)
          const player = cloud.shoplive.getPlayer(payload.campaignKey);
          if (player) player.sendMessage('removeCoupon');
        } else {
          alert('All coupons have been claimed.');
        }
      });
  },
  // CLICK_PRODUCT is optional — leave it out and the default (open in a new window) applies.
  // Add it only when you want something different, such as same-window navigation.
  // CLICK_PRODUCT: function (payload) {
  //   location.href = payload.url;
  // },
  LOGIN_REQUIRED: function (payload) {
    // A guest reached a feature that requires login
  },
};
cloud.shoplive.initPlugin({
  accessKey: "YOUR_ACCESS_KEY",
  messageCallback
});

Key actions

The bold numbers under When it fires refer to the picture in the screen glossary — so you can see at a glance what the viewer tapped to produce each action.

CLICK_SHARE_BTN: function (payload) {
  // your own handling, logging and so on
  console.log('share tapped', payload.campaignKey);

  // to keep the default behavior, rebuild it yourself
  // if payload.shareUrl is empty you must construct the address the SDK would have used
  if (navigator.share) {
    navigator.share({ title: payload.title || '', text: '', url: payload.shareUrl });
  } else if (navigator.clipboard) {
    navigator.clipboard.writeText(payload.shareUrl);
  }
}

For banner (⑪), coupon (⑨) and notice (⑩) popups, the click behavior is configured per popup in Admin. Here is the full set.

If you configured a click action but your registered callback is never called, check in Admin whether it is actually set to one of the "not needed" rows above.

Notify-only events — nothing to override

Events coming up from the player always carry payload.campaignKey so you can tell which broadcast they came from. That applies to events not listed separately in the table below as well.

The events below have no SDK default behavior. Registering one replaces nothing; it simply tells you "this happened". Use them to send analytics or to keep your own UI in sync.

The liveMiniPreview on ON_PLUGIN_INITIALIZED is the final result — your Admin settings with the SDK defaults filled in (position BOTTOM_RIGHT · margin 16 · duration 300). Read it when you need to move your own UI out of the mini preview's way.

const messageCallback = {
  ON_PLAYER_STARTED: function (payload) {
    analytics.track('live_player_started', { campaignKey: payload.campaignKey });
  },
  ON_PLAYER_MODAL_HIDDEN: function (payload) {
    // the modal closed, so restore your own page state
    document.body.classList.remove('live-open');
  }
};
cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY', messageCallback });

/* collapse this area while the viewer is typing */
#shoplive-player.CHAT_READY ~ .my-product-section {
  display: none;
}

Goods payload structure (CLICK_PRODUCT)

The add-to-cart action (CLICK_PRODUCT_CART) uses the same Goods structure as its payload.

Campaign payload structure (broadcast info)

Events that happen at the broadcast level — a broadcast-list tap, a modal opening, the mini preview — carry broadcast information with them. These six fields are always present.

Depending on the event, extra values such as tags · memo · backgroundUrl may ride along. Fields beyond these six vary per event, so check with console.log(payload) before relying on them.

User behavior logging (optional)

To track in-player UI taps — likes, shares, chat sends — in your own analytics, register the EVENT_LOG action. Unlike the actions above there is no business logic to handle; it is pure logging, so you can use it right away with no enabling request.

EVENT_LOG: function (payload) {
  console.log(payload.name, payload.feature, payload.parameter);
  // e.g. payload.name is 'like_button', 'share_button', 'chat_send_button', 'coupon', ...
}

Trackable event names

payload.feature tells you the kind — click is something the viewer tapped, show is something that appeared, action is everything else.

If a broadcast has no coupons, quizzes or Q&A, those events simply never fire. If a name arrives that is not on this list it is newly added — just record the payload as-is.

Measuring watch time

While the player is active, player_active_seconds arrives every 3 seconds. Cumulative watch time is already computed for you in parameter.activatedDuration, so there is nothing to add up yourself.

EVENT_LOG: function (payload) {
  if (payload.name === 'player_active_seconds') {
    const p = payload.parameter;
    // the SDK computes cumulative watch time for you (milliseconds)
    analytics.track('live_watch', {
      campaignKey: payload.campaignKey,
      mode: p.mode,                       // LIVE / REPLAY / PREVIEW
      seconds: Math.floor(p.activatedDuration / 1000)
    });
  }
}

Accumulation starts while the broadcast is ONAIR and the tab is visible. Time with the tab hidden is not included in activatedDuration, so there is no need to filter it out yourself with player_on_foreground / player_on_background.

Verify completion

• Your registered callback is called when a coupon is tapped
• Product information arrives in the payload when a product is tapped
• LOGIN_REQUIRED is called when a guest taps chat or another login-required feature

Previous ← Mission 2 · Connect user infoNext → Mission 4 · Promote the broadcast on other pages

Where Mission 1 was "where do I draw the broadcast", this mission is how do I get people there. There are three independent tools — use only the ones you need.

Mini preview — show a live broadcast in the corner of another page

While a broadcast is live, a small banner appears in the corner of pages other than the broadcast page and previews it. Tapping it takes the viewer straight into the modal player.

No separate call is needed. Just put initPlugin() on the pages where you want the preview and it appears automatically whenever a broadcast is live. In practice that usually means adding the initialization code to your shared layout once.

<!-- once, in the shared layout (the head area every page includes) -->
<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });
</script>

When it appears, and when it does not

There is one principle — it never appears on a page where the viewer is already watching. The point is to bring people to the broadcast, and they are already there; showing it would only cover the screen. The remaining conditions exist to avoid showing it twice.

Showing and hiding it yourself optional

If you do not want it appearing on its own and would rather show it only at moments you choose, switch off the automatic display at initialization and call it yourself.

// turn off automatic display at initialization
cloud.shoplive.initPlugin({
  accessKey: 'YOUR_ACCESS_KEY',
  useAutoPreview: false
});

// then, whenever you like
cloud.shoplive.showLiveMiniPreview();     // show
cloud.shoplive.dismissLiveMiniPreview();  // hide

Turning off automatic display does not lift the blocking conditions above — calling showLiveMiniPreview() directly still does nothing inside an iframe or during the grace period.

Changing what a tap does optional

The default is to open the modal player. To send viewers to your own live page instead, intercept it like this.

cloud.shoplive.setOnClickLiveMiniPreview(function (campaign) {
  // campaign carries campaignKey · title · campaignStatus and more
  location.href = '/live?ck=' + campaign.campaignKey;
});

You can observe the banner appearing, disappearing and being dismissed through the notification events (ON_LIVE_MINI_PREVIEW_SHOWN · ON_LIVE_MINI_PREVIEW_HIDDEN · ON_CLICK_CLOSE_LIVE_MINI_PREVIEW).

Position and size

Neither is changed from your code — position and margins come from Shoplive Admin settings, and the size is decided by the viewport width. Use this when moving your own UI out of the way.

Position

You can read the values currently in effect from the ON_PLUGIN_INITIALIZED event — useful for placing your own UI (a floating button, say) clear of where the mini preview will land. Note that once a viewer drags it, the actual position differs.

Size

The ratios are 9:15 and 15:9, not 9:16 and 16:9. Keep that in mind when aligning to the pixel.

Share URLs — open that broadcast from a single link

This covers the address the player's share button (ui.shareButton) produces, and what happens when someone arrives on it. Both the parameter appended and the resulting behavior depend on whether you set shareUrl, so read the two cases separately.

// if you set shareUrl — open it yourself on the receiving side
const ck = new URLSearchParams(location.search).get('ck');
if (ck) {
  cloud.shoplive.showFeaturedPlayerModal({ campaignKey: ck });
  // or cloud.shoplive.setPlayer('shoplive-player', { campaignKey: ck });
}

To record marketing attribution, add utm_source · utm_medium · utm_campaign · utm_content to your share and ad addresses. The SDK reads them and stores them alongside watch and conversion records (Mission 6).

With no utm_source, an advertising ID parameter is used instead — the first of adid · adId · adld · adLd · ad-ld · ad-id · ad-Id that is found. If your ad platform emits adid, it is picked up without editing the address.

Broadcast cards and live covers optional

Use these when a whole list (Approach C) is more than you need and you only want one specific broadcast, or want to show something only while a broadcast is live.

<div id="live-card"></div>
<script>
  cloud.shoplive.setLivePreview('live-card', {
    campaignKey: 'YOUR_CAMPAIGN_KEY',
    onClick: function (campaign) {
      cloud.shoplive.showFeaturedPlayerModal({ campaignKey: campaign.campaignKey });
    }
  });
</script>

<div id="on-air-cover"></div>
<script>
  cloud.shoplive.setOnAirCover('on-air-cover');
</script>

Whether the cover actually appeared is reported by the ON_ONAIR_COVER_SHOWN event in payload.show — handy for filling that space with a different banner when no broadcast is live.

Verify completion

• While a broadcast is live, the mini preview appears in the corner of other pages carrying the initialization code
• Tapping the mini preview opens the modal player (or runs the behavior you defined)
• Copying the address bar mid-playback and pasting it into a new tab opens the same broadcast

Previous ← Mission 3 · Handle user interactionsNext → Mission 5 · Control the player

Where Mission 3 was "receiving what the player tells you", this mission goes the other way. You grab the player object and send it commands.

Gathered onto one page, from loading the SDK to sending a command, it looks like this. Steps 1, 2 and 4 are exactly Mission 1, Approach A; what this mission adds is 3 and 5.

<!-- 1. Load the SDK -->
<script src="https://static.shoplive.cloud/shoplive.js"></script>

<!-- 2. Where the player goes -->
<div id="shoplive-player"></div>

<!-- 3. (optional) your own UI for driving the player — here, a mute button outside it -->
<button type="button" id="mute-btn">Mute</button>

<script>
  // 4. initialize and show the player (Mission 1)
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });
  cloud.shoplive.setPlayer('shoplive-player', { campaignKey: 'YOUR_CAMPAIGN_KEY' });

  // 5. (optional) send a command — here, when the outside button is pressed
  document.getElementById('mute-btn').addEventListener('click', function () {
    const player = cloud.shoplive.getPlayer('YOUR_CAMPAIGN_KEY');
    if (!player) return;              // not up yet — do nothing
    player.sendMessage('mute');
  });
</script>

Steps 3 and 5 are just one way of doing it, chosen for this example. It shows a button outside the player that mutes on tap, but you can send a command from anywhere — other UI on your page, your own logic on scroll or a timer, or inside any Mission 3 callback. Grab the player with getPlayer() and send. If all you plan to do is show the player, you do not need this mission at all.

cloud.shoplive.initPlugin({
  accessKey: 'YOUR_ACCESS_KEY',
  messageCallback: {
    // right after playback starts — the player definitely exists at this point
    ON_PLAYER_STARTED: function (payload) {
      const player = cloud.shoplive.getPlayer(payload.campaignKey);
      if (player) player.sendMessage('hideControls');
    }
  }
});

cloud.shoplive.setPlayer('shoplive-player', { campaignKey: 'YOUR_CAMPAIGN_KEY' });

Getting hold of the player

These values can be read straight off the player object.

Commands you can send

The shape is player.sendMessage(command, payload). These are the ones used in customer integrations.

// 1) ask
cloud.shoplive.getPlayer(PAGE_CAMPAIGN_KEY).sendMessage('GET_CURRENT_PLAYBACK_TIME');

// 2) receive
const messageCallback = {
  CURRENT_PLAYBACK_TIME: function (payload) {
    payload.playbackTimeInSeconds;  // 132.4  (number, seconds)
    payload.playbackTime;           // '00:02:12'  (HH:mm:ss string)
  },
};

const messageCallback = {
  DOWNLOAD_COUPON: function (payload) {
    fetch('YOUR_COUPON_API', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ coupon: payload.coupon })
    })
      .then(function (res) { return res.json(); })
      .then(function (res) {
        // the player may have closed while we waited, so grab it again here
        const player = cloud.shoplive.getPlayer(payload.campaignKey);
        if (!player) return;

        if (res.success) {
          player.sendMessage('showDialog', {
            title: 'Coupon issued',
            message: 'Coupon ' + payload.coupon + ' has been issued.'
          });
          player.sendMessage('removeCoupon');   // clear the claimed coupon from the screen
        } else {
          player.sendMessage('showToast', { message: 'All coupons have been claimed.' });
        }
      })
      .catch(function () {
        const player = cloud.shoplive.getPlayer(payload.campaignKey);
        // doing nothing on failure makes the tap feel unresponsive to the viewer
        if (player) player.sendMessage('showToast', { message: 'Please try again in a moment.' });
      });
  }
};

cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY', messageCallback });

Two things in that example are worth calling out.

• It is getPlayer(payload.campaignKey), not getPlayer(). Called with no argument, a live (ONAIR) broadcast wins, so with several players on a page the dialog could land on a player other than the one whose coupon was tapped. The event payload carries campaignKey, so just pass it through.
• The player is grabbed again after await / then. If the viewer closes the modal while you wait for the server, that player is gone. Sending a message through the object you captured on the first line of the callback delivers it nowhere.

If you have seen a command name that is not in the table above, it belongs to the mobile SDK WebView or a Shoplive operations tool. It is not used in web integrations.

Verify completion

• getPlayer() returns a player object and its campaignKey matches the broadcast you opened
• Sending removeCoupon after a coupon tap makes the coupon popup disappear
• A dialog sent with showDialog appears over the player

Previous ← Mission 4 · Promote the broadcast on other pagesNext → Mission 6 · Measurement — traffic and purchases

SDK tracking ends the moment a viewer taps a product and leaves for the product page. Whether the payment went through after that is something only your pages know, so you report it once at purchase time — that is what makes "how much revenue did this broadcast create" measurable.

Where they came from — marketing traffic tracking

Add parameters beginning with utm_ to your broadcast page address and the SDK reads them, recording which channel each viewer arrived from. You can then separate the watching and buying of people who came from an Instagram banner from those who came from a text message.

You do not need all four — add only the ones you need.

https://my-shop.com/live?utm_source=instagram&utm_medium=banner&utm_campaign=spring_sale

The values read here ride along with purchase conversion reports automatically. There is nothing extra to pass, and traffic → watching → purchase connects into one line.

You can break the results down by traffic channel in the Shoplive Admin statistics.

Arriving from an ad platform

Ad platforms attach their own tracking parameters to links. The SDK passes the whole page address through to the player, so there is nothing for you to handle — as long as that address survives intact.

• Web — do not strip the query string on the landing page the ad link reaches. If you pass through a redirect, carry the query across as-is
• Hybrid app (WebView) — when the app takes the ad link and opens a WebView, it must copy the query into the WebView URL verbatim. For the WebView settings themselves, see Appendix D
• Native app — this is deep-link handling in the iOS and Android native SDKs, not the web SDK. Contact your Shoplive representative

Advertising identifiers are also accepted as adId — spellings such as adid and ad-id are recognized too.

Purchase conversion, step 1 · Where it goes

A page that opens exactly once after the order is confirmed — usually the order-complete or payment-complete page. Put it on a cart or checkout screen and abandoned orders get counted as purchases; put it on a page that reopens on refresh and the same order is reported more than once.

Purchase conversion, step 2 · Sending it

The order is: load the SDK → initialize → user info → report. Calling sendConversionEvent() before initialization finishes is fine — the SDK queues it and runs it later, so ordering alone will not make it fail.

<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });

  // for logged-in users, pass the "same" userId used while watching (see step 3)
  cloud.shoplive.setUserObject({ userId: 'MEMBER_ID' });

  cloud.shoplive.sendConversionEvent({
    accessKey: 'YOUR_ACCESS_KEY',   // required
    eventType: 'purchase',          // required — 'purchase' (completed) / 'cartIn' (added to cart)
    orderId: 'UNIQUE_ORDER_ID',     // your order number
    products: [
      { productId: 'PRODUCT_ID_1', sku: 'PRODUCT_SKU_1', purchaseUnitPrice: 10000, purchaseQuantity: 1, currency: 'KRW' },
      { productId: 'PRODUCT_ID_2', sku: 'PRODUCT_SKU_2', purchaseUnitPrice: 15000, purchaseQuantity: 2, currency: 'KRW' }
    ]
  });
</script>

If the address carries UTM parameters such as utm_source, they travel with this request — so add UTM to your traffic addresses if you want conversions split by ad and share source.

Each item in the products array:

"Required" here follows the SDK type declarations. In practice only accessKey and eventType are checked before sending, so the request still goes out with fields missing — it may just be silently dropped from the aggregation, so fill them in.

Purchase conversion, step 3 · How it is matched to watch records

The watch record and the purchase report travel as two separate requests. The player sends the watch record once the video has been watched for 3 seconds or more; the purchase is sent by sendConversionEvent() above. The server stitches the two together by identifier, and that is what completes a conversion. So if the identifiers do not line up, neither record counts as a conversion even though both exist — one of these three must match.

On store platforms optional

On platforms where you cannot build the order-complete page yourself, put the same call in the places below. The only difference is filling the order number and product details from what the platform gives you.

Cafe24

Add it just before </body> in the skin's order_result.html (the order-complete screen). The order number comes from {$order_id}, which Cafe24 fills in, and the ordered items are fetched through the Cafe24 API.

<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });

  const orderId = '{$order_id}';   // Cafe24 replaces this with the real order number

  // for a member order, pass the same userId used while watching
  // cloud.shoplive.setUserObject({ userId: 'MEMBER_ID' });

  cloud.shoplive.sendConversionEvent({
    accessKey: 'YOUR_ACCESS_KEY',
    eventType: 'purchase',
    orderId: orderId,
    products: [
      // fill in the items fetched from the Cafe24 API as { productId, sku, purchaseUnitPrice, purchaseQuantity, currency }
    ]
  });
</script>

Fetching the ordered items through the Cafe24 API (CAFE24API.getOrderDetailInfo) requires an app key. Ask your Shoplive representative for it.

Shopify

You cannot place a script on the checkout-complete screen directly, so register it as a custom pixel and call it on checkout_completed.

const script = document.createElement('script');
script.src = 'https://static.shoplive.cloud/shoplive.js';
script.async = true;
document.head.appendChild(script);

script.onload = function () {
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });

  analytics.subscribe('checkout_completed', function (event) {
    const checkout = event.data.checkout;

    // for a member order, derive userId the same way you did while watching
    const customerId = checkout.order.customer && checkout.order.customer.id;
    if (customerId) {
      cloud.shoplive.setUserObject({ userId: String(customerId) });
    }

    cloud.shoplive.sendConversionEvent({
      accessKey: 'YOUR_ACCESS_KEY',
      eventType: 'purchase',
      orderId: checkout.order.id,
      products: checkout.lineItems.map(function (item) {
        return {
          productId: item.variant.product.id,
          sku: item.variant.sku,
          purchaseUnitPrice: parseFloat(item.variant.price.amount),
          purchaseQuantity: item.quantity,
          currency: item.variant.price.currencyCode
        };
      })
    });
  });
};

Verify completion

• The network tab on the order-complete page records exactly one /conversion/event request
• Refreshing or going back does not report the same order again
• (Logged in) the userId on that request matches the one passed while watching
• Results appear in the conversion report in Shoplive Admin — it may take some time to show up

Previous ← Mission 5 · Control the playerNext → Full example

Gathering everything so far onto one page gives you the shape below. For a real service you only fill in YOUR_ACCESS_KEY, YOUR_CAMPAIGN_KEY and the logic inside the callbacks. Purchase conversion (Mission 6) belongs on the order-complete page rather than this one, so it is shown separately below.

The live page

<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
  // ── Mission 3 · handling user interactions
  const messageCallback = {
    DOWNLOAD_COUPON: function (payload) {
      // call your coupon API, and clear the coupon from the screen only on success (Mission 5)
      fetch('YOUR_COUPON_API', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ coupon: payload.coupon })
      })
        .then(function (res) { return res.json(); })
        .then(function (res) {
          // the player may have closed while we waited, so grab it here
          const player = cloud.shoplive.getPlayer(payload.campaignKey);
          if (!player) return;
          if (res.success) {
            player.sendMessage('removeCoupon');
          } else {
            player.sendMessage('showToast', { message: 'All coupons have been claimed.' });
          }
        });
    },
    LOGIN_REQUIRED: function () {
      location.href = '/login?returnTo=' + encodeURIComponent(location.href);
    },
    ON_CLICK_CAMPAIGN_LIST_ITEM: function (payload) {
      // the default is to open a modal. Override it only to route to your own detail page
      // (if the modal default is fine, do not register this callback)
      location.href = '/live/' + payload.campaign.campaignKey;
    }
  };

  // ── Mission 1 · initialization (Mission 4 · setting the share URL)
  cloud.shoplive.initPlugin({
    accessKey: 'YOUR_ACCESS_KEY',
    messageCallback: messageCallback,
    shareUrl: 'https://my-shop.com/live'
  });

  // ── Mission 2 · connect the user if they are logged in (skip this whole block for guests)
  cloud.shoplive.setUserObject({ userId: 'YOUR_HASHED_USER_ID', userName: 'YOUR_USER_NAME' });

  // the broadcast pinned to this page
  const PAGE_CAMPAIGN_KEY = 'YOUR_CAMPAIGN_KEY';
</script>

<!-- ── Mission 1 · Approach A — one specific broadcast, right here -->
<div id="shoplive-player"></div>
<script>
  cloud.shoplive.setPlayer('shoplive-player', {
    campaignKey: PAGE_CAMPAIGN_KEY,
    ui: { shareButton: true }
  });
</script>

<!-- ── Mission 1 · Approach C — featured broadcast + list from the template (instead of Approach A) -->
<!--
<div id="shoplive-overall-area"></div>
<script>
  cloud.shoplive.setOverall('shoplive-overall-area');
</script>
-->

<!-- ── Mission 4 · if the visitor arrived through a share link, open that broadcast -->
<script>
  const ck = new URLSearchParams(location.search).get('ck');
  // do not stack a modal on top of the broadcast this page already shows
  if (ck && ck !== PAGE_CAMPAIGN_KEY) {
    cloud.shoplive.showFeaturedPlayerModal({ campaignKey: ck });
  }
</script>

The order-complete page

<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });

  // it must be the "same" userId as when they watched for the conversion to connect
  cloud.shoplive.setUserObject({ userId: 'YOUR_HASHED_USER_ID' });

  cloud.shoplive.sendConversionEvent({
    accessKey: 'YOUR_ACCESS_KEY',
    eventType: 'purchase',
    orderId: 'UNIQUE_ORDER_ID',
    products: [{
      productId: 'PRODUCT_ID',
      sku: 'PRODUCT_SKU',
      purchaseUnitPrice: 10000,
      purchaseQuantity: 1,
      currency: 'KRW'
    }]
  });
</script>

Previous ← Mission 6 · Measurement — traffic and purchasesNext → Appendix

Features that fall outside the missions and are only needed in particular situations.

A. Features that must be enabled

The four below only work once the feature is switched on for your account. If the button never appears even with the code in place, check that first — request it at ask@shoplive.cloud.

Brand favorites

The brand favorite button inside the player. When a viewer taps it, ON_CLICK_BRAND_FAVORITE_BUTTON arrives; you save it in your own system and report the result back to the player.

const messageCallback = {
  // when the player starts or the brand info changes — report the current user's favorite state
  ON_CHANGED_BRAND_FAVORITE: function (payload) {
    const player = cloud.shoplive.getPlayer(payload.campaignKey);
    if (!player) return;
    player.sendMessage('SEND_COMMAND_MESSAGE', {
      command: 'SET_BRAND_FAVORITE',
      payload: { identifier: payload.identifier, favorite: true }
    });
  },
  // when the viewer taps the button — save it on your server
  ON_CLICK_BRAND_FAVORITE_BUTTON: function (payload) {
    const { identifier, favorite } = payload;
    fetch('YOUR_FAVORITE_API', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ identifier, favorite })
    });
  }
};

cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY', messageCallback });

You can also pass the initial state when opening the player — setPlayer(id, { campaignKey, brand: { identifier, favorite } }).

Add to cart

A cart button appears in the product list, and tapping it delivers CLICK_PRODUCT_CART with a Goods payload. Add it to your own cart, then report the cart state back to the player and the button changes shape.

CLICK_PRODUCT_CART: function (payload) {
  addToMyCart(payload).then(function () {
    // the player may have closed while adding, so grab it here (Mission 5)
    const player = cloud.shoplive.getPlayer(payload.campaignKey);
    if (!player) return;
    player.sendMessage('SEND_COMMAND_MESSAGE', {
      command: 'SET_PRODUCT_CART_ON',
      payload: { products: [{ sku: payload.sku, isCartOn: true }] }
    });
  });
}

On a Shopify store using platform: 'SHOPIFY', the SDK handles adding to and reading the cart itself, so you do not need to implement the callback above.

Broadcast reminders

A "Subscribe" button appears under the card title of broadcasts in the upcoming (READY) state. You turn it on in initPlugin(), in one of two ways: for every upcoming broadcast, or for specific broadcasts only.

Option 1 · Show on every upcoming broadcast

Add a single line, useRemind: true, inside webClientSettings. Upcoming broadcasts registered later pick it up automatically.

cloud.shoplive.initPlugin({
  accessKey: 'YOUR_ACCESS_KEY',
  webClientSettings: {
    useRemind: true
  }
});

Option 2 · Show on specific broadcasts only

Pass the campaignId of each broadcast that should show the button as an array of strings. Broadcasts not in the list get no button. Note that the values are campaignId, not campaignKey — a different value from the broadcast key used everywhere else in this guide. You can find it on the broadcast detail page in Admin.

cloud.shoplive.initPlugin({
  accessKey: 'YOUR_ACCESS_KEY',
  listCampaignIdsForRemindButton: ['2262194', '2262195']
});

How the two settings combine

The two settings can be used together. When useRemind is on, the button shows on every upcoming broadcast regardless of the list.

Receiving the button click

Tapping the button delivers ON_CLICK_REMIND_CAMPAIGN, and payload.isReminded tells you whether the viewer is signing up or cancelling. Hook your own reminder scheduling into this callback.

ON_CLICK_REMIND_CAMPAIGN: function (payload) {
  const campaignKey = payload.campaign.campaignKey;
  if (payload.isReminded) {
    subscribeToMyPush(campaignKey);     // sign up for the reminder
  } else {
    unsubscribeFromMyPush(campaignKey); // cancel the reminder
  }
}

The button only appears while the broadcast is upcoming. It disappears on its own once the broadcast starts or ends. Code settings take precedence over Admin — even if reminders are enabled in Admin, passing useRemind: false turns the button off. The sign-up state is stored in the browser — after signing up, the same browser shows the button as "Completed", and tapping it again cancels.

Auctions

Real-time auctions. The one thing you absolutely must handle is sending the winner to checkout; the rest of the events are only for building your own UI or logging.

Sending the winner to checkout

When the auction ends, a sheet appears for the winner. Tapping the checkout button on that sheet delivers ON_AUCTION_WINNER_CHECKOUT_CLICKED.

ON_AUCTION_WINNER_CHECKOUT_CLICKED: function (payload) {
  // payload.auction.winnerCheckoutScheme carries the checkout address configured in Admin
  const scheme = payload.auction && payload.auction.winnerCheckoutScheme;
  location.href = scheme || ('/checkout?sku=' + payload.product.sku);
}

Payload structure

The auction events below all share the same payload shape — two blocks, product and auction.

Following the auction's progress

Bidding eligibility

If a viewer tries to bid without eligibility, CAN_BID_REQUIRED arrives with { isLogin: true, canBid: false }. Guests get LOGIN_REQUIRED instead of this event — they have to log in first.

B. PIP — keep the broadcast playing across pages

When a viewer taps a product mid-broadcast, they move to the product page and the broadcast stops. PIP lets the page change while keeping just the video, small, so they keep watching.

It is a feature Shoplive turns on by request (ask@shoplive.cloud). Once it is on, there is nothing to add to your code — the SDK switches to PIP on its own when a viewer taps a product.

Two mechanisms

Three things to check before using web PIP

Web PIP works by loading the destination page into an iframe covering the whole screen. So if any one of these applies, the screen will not render even with the feature on. Check before requesting it.

Payment and login pages drop out automatically

Some pages, payment above all, must not run inside an iframe. So the moment web PIP navigates to one of these addresses, it releases PIP and switches to a real page navigation.

/orderform.html   /login.html   /basket.html   /navercheckout

Browser PIP limitations

• It only engages from an action the viewer performed directly. That is a browser security rule, so it cannot be invoked arbitrarily from code.
• You cannot switch to PIP and open a new window in the same action. If you need both, do the PIP switch first and open the window as a separate action.
• Mobile support is weak. Desktop browsers generally handle it well, but in Android WebViews (web screens inside your app, and in-app browsers such as KakaoTalk or Instagram) it is limited or entirely non-functional. If most of your viewers are on mobile or arrive through an app WebView, browser PIP alone is not enough — cover same-domain flows with web PIP and leave only the flows that exit to external domains to browser PIP.

Triggering it from your own code optional

The default is automatic — when a viewer taps a product or link inside the player, the SDK switches to PIP on its own (the default behavior of CLICK_PRODUCT and LINK in Mission 3). To trigger the same thing from another button in your own UI, use this.

// switches to web PIP and navigates to the given address
cloud.shoplive.navigateWithPIP('/product/1', 'YOUR_CAMPAIGN_KEY');

Nothing happens if web PIP is not enabled or there is no player for that broadcast. While in PIP, tapping the small player releases PIP and returns to the broadcast screen.

C. Using it in an SPA

• initPlugin({ isSPA: true }) — keeps the SDK alive across client-side route changes. initPlugin runs once per page lifetime; a second call is ignored.
• Clean up with destroyPlayer(id) and destroyOverall(id, true) when components unmount. Removing only the container DOM leaves the player alive inside the SDK.
• If your own router watches for URL changes, turn on disableHistoryHook so modals leave the address alone. You can apply it page-wide with initPlugin({ disableHistoryHook: true }).

D. Inside your app's WebView

When the page carrying the broadcast is opened in your app's WebView (a hybrid app), the video will not play, or will jump to full screen, unless you change the WebView settings. The following are set once, in the app code.

// iOS — when creating the WKWebView
let configuration = WKWebViewConfiguration()
configuration.allowsInlineMediaPlayback = true
let webView = WKWebView(frame: rect, configuration: configuration)

// Android — after creating the WebView
webView.settings.mediaPlaybackRequiresUserGesture = false

E. RequireJS / AMD environments

The SDK uses hls.js for video playback. Normally it loads it directly from https://cdnjs.cloudflare.com with a <script> tag (allow that origin too if you use a CSP), but if your page manages modules with RequireJS and that route is blocked, hand it a loader to fetch hls.js on its behalf.

cloud.shoplive.initPlugin({
  accessKey: 'YOUR_ACCESS_KEY',
  useAMD: true,
  AMDLoader: require   // omit it and window.require is used
});

• If window.Hls already exists on the page, useAMD does nothing — the SDK uses that object as-is.
• Omitting AMDLoader falls back to window.require. With neither available, the console logs Invalid AMDLoader requirejs and it stops — and the video will not play. If playback fails with no other error, check for that log first.
• In an ordinary <script>-loading environment you will never need this.

F. Alongside the Shortform SDK

Live (shoplive.js) and Shortform (shoplive-shortform.js) are separate scripts, but both add functions to the same window.cloud.shoplive object, so they can be loaded on one page. Load order does not matter.

• Initialize each one separately — initPlugin() / initShortform()
• The user functions (setUserObject · setUserJWT · logout) are shared by both SDKs, so calling once applies to both. The last call wins
• The live mini preview and the Shortform preview do not know about each other. Both default to a screen corner, so they can overlap in the same spot — if you use both, move one to a different corner. For the live side see Mission 4 · position and size; for Shortform see the Shortform guide

For how to integrate Shortform, see the Shortform guide.

G. Where to install on each shop platform

For stores built on Cafe24, Godomall, WISA, MakeShop, imweb, or Shopify, this section shows where in each admin to put the code. The code itself is the same as in Mission 1 (live list and player) and Mission 2 · Step 3 (login auto-link). Here we cover only the locations and each platform's member variables.

① Common layout

<!-- Common layout — once on every page (where: see each platform below) -->
<script src="https://static.shoplive.cloud/shoplive.js"></script>
<!-- Member info elements — per platform (see each platform below) -->
<script>
  cloud.shoplive.initPlugin({
    accessKey: 'YOUR_ACCESS_KEY',   // copy it from the campaign details in Admin
    platform: 'CAFE24'              // the value for your platform (omit for imweb)
  });
</script>

② Live list page

<!-- Live list page — in this page's HTML area -->
<div id="shoplive-overall"></div>
<script defer>cloud.shoplive.setOverall('shoplive-overall');</script>

Cafe24

Member info elements

<div module="Layout_stateLogon" style="display:none;">{$id} {$name}</div>

Godomall

Member info elements

<div style="display:none;">
  <span id="cloud-shoplive-user-id">{=gSess.memId}</span>
  <span id="cloud-shoplive-user-name">{=gSess.memNm}</span>
</div>

WISA

Member info elements

<div style="display:none;">
  <span id="cloud-shoplive-user-id">{{$회원아이디}}</span>
  <span id="cloud-shoplive-user-name">{{$회원명}}</span>
</div>

MakeShop

Member info elements

<div style="display:none;">
  <span id="cloud-shoplive-user-id"><!--/user_id/--></span>
  <span id="cloud-shoplive-user-name"><!--/user_name/--></span>
</div>
<script>cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY', platform: 'MAKESHOP' });</script>

imweb

<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });
  if (window.MEMBER_UID) {            // member number imweb sets for a signed-in member
    cloud.shoplive.setUserObject({ userId: window.MEMBER_UID });
  }
</script>

Shopify

Connect with the Shopify app (ShopliveAssistant) — recommended

1. On the ShopliveAssistant page in the Shopify App Store, use the account icon at the top right to check that it's the right store
2. Install → review the permissions the app asks for (staff info, product data, and more) and finish the install
3. In Shopify admin, go to Apps › Shoplive Assistant and sign in with your Shoplive account
4. Check the Access Key linked to the store (you can edit it), and use Product sync to bring Shopify products into Shoplive — recent changes only, or each option as a separate product
5. The app covers the account link and product sync only. Install the player with the theme code below

theme.liquid — pass the signed-in customer with Liquid variables

<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
  cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY', platform: 'SHOPIFY' });
  {% if customer %}
  cloud.shoplive.setUserObject({ userId: "{{ customer.id }}", userName: "{{ customer.first_name }}" });
  {% endif %}
</script>

<div id="shoplive-overall"></div>
<script defer>
  document.addEventListener('DOMContentLoaded', function () {
    cloud.shoplive.setOverall('shoplive-overall');
  });
</script>

Previous ← Full exampleNext → Function index

Every cloud.shoplive.* function used in web integrations. Use it to find the right section when you already know the name.

If you see a name on cloud.shoplive that is not in this table, it belongs to the mobile app SDK integration or is internal to Shoplive. It is not used in web integrations.

Previous ← AppendixNext → Config object field dictionary

A collected list of what you can put in the config object passed to each function. Apart from accessKey and campaignKey, almost everything is optional — set what you need and leave the rest out to run on defaults or your account settings.

Initialization — initPlugin(config)

If you have seen a value that is not listed here. It is either something the app passes when opening the SDK in a mobile WebView (advertising identifiers and the like), something agreed individually with a specific customer, or a Shoplive development value. None of it applies when integrating directly into a web page.

Player — setPlayer(containerId, config)

Live page template — setOverall(containerId, config)

Other functions

User info — setUserObject(user)

Everything except userId is optional. For JWT claim names see Mission 2 · step 5 (the chat display name is name, not userName).

Previous ← Function indexNext → Event dictionary

Every event you can register on initPlugin({ messageCallback }). How to use them, with examples, is in Mission 3; this page is for finding one quickly by name. The numbers in the Screen column match the picture in the screen glossary.

Events with a default behavior — registering one replaces it

The SDK handles these for you if you leave them alone. The moment you register one, the default stops running — so even if you only meant to log, you must reimplement the original behavior yourself.

Events with no default — nothing happens unless you register

For these three, the click action chosen in the Shoplive Admin popup settings becomes the event name delivered. If the configured action and the event name you registered do not match, your callback is never called — read the Admin settings table in Mission 3 alongside this.

Notify-only events

ON_PLUGIN_INITIALIZED · ON_PLAYER_STARTED · NOW_ONAIR_CHECKED · ON_CAMPAIGN_STATUS_CHANGED · ON_CHANGED_VIEWER_STAT · ON_PLAYER_MODAL_SHOWN · ON_PLAYER_MODAL_HIDDEN · ON_LIVE_MINI_PREVIEW_SHOWN · ON_LIVE_MINI_PREVIEW_HIDDEN · ON_CLICK_CLOSE_LIVE_MINI_PREVIEW · ON_PRODUCT_LIST_SHOWN · ON_CHANGED_CAMPAIGN_PRODUCT_LIST · ON_FILTERED_CHAT · ON_RECEIVED_CHAT · ON_ERASED_CHAT · ON_CHAT_INPUT_FOCUS_IN · ON_CHAT_INPUT_FOCUS_OUT · ON_UID_ISSUED — for when each fires and its payload, see Mission 3 · notify-only events.

An event that only arrives as a response — CURRENT_PLAYBACK_TIME comes only after you send GET_CURRENT_PLAYBACK_TIME. It never fires on its own.

Events for features that must be enabled

Behavior log — EVENT_LOG

Collects in-player button taps and impressions into a single event. The full list of all 51 names is in Mission 3 · user behavior logging.

If an event name arrives that is not in this document, it belongs to the mobile SDK WebView, a Shoplive operations tool, or a feature agreed individually with a specific customer. An ordinary web integration does not need to handle it.

Previous ← Config object field dictionaryNext → Player command dictionary

Commands you can send with getPlayer().sendMessage(command, payload). How to use them is in Mission 5. The numbers in the Screen column match the picture in the screen glossary.

SEND_COMMAND_MESSAGE sub-commands

Used to report state back for features that must be enabled first.

const player = cloud.shoplive.getPlayer();

player.sendMessage('SEND_COMMAND_MESSAGE', {
  command: 'SET_PRODUCT_CART_ON',
  payload: { products: [{ sku: 'PRODUCT_SKU', isCartOn: true }] }
});

If you have seen a command name that is not in this table, it belongs to the mobile SDK WebView or a Shoplive operations tool. It is not used in web integrations.

Previous ← Event dictionaryNext → Troubleshooting & FAQ