Product Tagging

SDK v7.x · Last verified March 2026 · iOS · Android · Web

Platform note — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift) and Android (Kotlin) SDKs — see the linked SDK reference in each step.

Speed run — just the code

import { PostRepository } from '@amityco/ts-sdk';

// 1. Create a room post with product tags + pinned product
const post = await PostRepository.createRoomPost({
  targetType: 'community', targetId: communityId,
  data: { roomId: room.roomId, title: 'Flash Sale Live!' },
  productTags: [
    { productId: 'prod_001', text: 'Nike Air Max', index: 0, length: 12 },
    { productId: 'prod_002', text: 'Adidas Ultra', index: 13, length: 12 },
  ],
  pinnedProductId: 'prod_001',
});

// 2. Swap pinned product mid-stream (uses CHILD post ID)
await PostRepository.pinProduct(childPostId, 'prod_002');

// 3. Unpin when done showcasing
await PostRepository.unpinProduct(childPostId);

Full walkthrough below ↓

Livestream with a pinned product card (GlowLab Soft Glow Blush Stick, $24) at the bottom, Unpin button, viewer count, and live chat — Pinned product overlay during a live broadcast with chat and viewer count

Product tagging turns a livestream into a shoppable experience. Hosts tag products from the catalog, pin one at a time as a prominent overlay, and viewers can browse and click through — all without leaving the stream.

Prerequisites:

A room and livestream post already exist → Go Live & Room Management
Product Catalog is configured and enabled in your Admin Console
Available on iOS, Android, and Web only (Flutter / React Native not yet supported)

Child Post ID — pinProduct, unpinProduct, and updateProductTags all operate on the child room post, not the parent. Use the child post ID returned at creation.

How Product Tagging Works

Phase	Who can tag	Who can pin
Pre-live (backstage)	Host only	Host only
During livestream	Host + co-host (if granted)	Host + co-host (if granted)
Post-live (management)	Host only	—

Viewers can browse and open tagged products during all phases, including replay.

Limit	Value
Max products per livestream	20
Simultaneously pinned products	1

Admin Console: Set Up Your Product Catalogue

Before you can tag products in a livestream, your catalogue must be populated in Admin Console → Product catalogue.

Open the Product Catalogue

Navigate to Product catalogue in the Admin Console sidebar.

Admin Console Product Catalogue showing product list with IDs, names, prices, statuses, and action buttons — Product Catalogue dashboard — search, filter, import, and manage products

Add products

Click + Add product to create products individually, or use Import to upload a CSV for bulk creation. Each product needs an ID, name, URL, and status set to Active.

Admin Console Add Product form with fields for Product ID, Status, Product name, Product URL, Price, and image upload — Add product form — product ID, name, URL, price, and thumbnail image

Verify products are Active

Only products with Active status show up in the tag-product search on the app side. Archived products are hidden from tagging.

Full Admin Console guide → Product Catalogue

In-App: Tag & Pin Products

Once products exist in the catalogue, hosts (and co-hosts with permission) can tag and pin them during the stream.

Tag products

Manage tagged products

Tagged products management view showing pinned product, other products with Pin and Delete buttons, and Add products button — Pin, unpin, and remove tagged products

Viewer experience

Viewers see a tag icon with a badge count. Tapping opens a scrollable product list with prices and “View” buttons.

Products tagged bottom sheet showing product thumbnails, names, prices, Pinned badge on first item, and View buttons — Viewer's product list — browse tagged products without leaving the stream

Step-by-Step Implementation

Create a room post with product tags

Attach products at creation time. Optionally pre-pin one.

const post = await PostRepository.createRoomPost({
  targetType: 'community',
  targetId: communityId,
  data: {
    roomId: room.roomId,
    title: 'Flash Sale',
    text: 'Flash Sale Live! Check out Nike Air Max!',
  },
  productTags: [
    { productId: 'prod_001', text: 'Nike Air Max', index: 38, length: 12 },
  ],
  pinnedProductId: 'prod_001',
});

Full reference → Product Tagging SDK

Pin and swap products mid-stream

Only one product can be pinned at a time. Pinning a new product automatically replaces the previous one — no need to unpin first.

// Pin a product (uses CHILD post ID)
await PostRepository.pinProduct(childPostId, 'prod_002');

// Unpin the current product
await PostRepository.unpinProduct(childPostId);

Update the tag list during the stream

updateProductTags does a full replacement. To add a product, merge it with the existing array. If the currently pinned product is not in the new array, it is automatically unpinned.

await PostRepository.updateProductTags(childPostId, [
  { productId: 'prod_001' },
  { productId: 'prod_002' },
  { productId: 'prod_003' },
]);

Grant co-host product permissions

By default co-hosts cannot manage products. The host must explicitly grant permission.

await RoomRepository.updateCohostPermission(
  room.roomId,
  'cohost_456',
  true, // canManageProductTags
);

Full reference → Co-Host Management

Track product engagement

Fire view and click analytics to measure which products drive the most interest.

// When a product card becomes visible
product.analytics.markAsViewed(
  'livestream_page/product_list/product_item',
  AnalyticsSourceTypeEnum.ROOM,
  roomId,
);

// When a viewer taps the product link
product.analytics.markAsClicked(
  'livestream_page/product_list/product_item',
  AnalyticsSourceTypeEnum.ROOM,
  roomId,
);

Events are fire-and-forget and automatically deduplicated per product per source.

UIKit: Pre-Built Product Tagging Components

If you’re using UIKit, the product tagging UI is handled with two shared components:

Component	Used for	Platforms
`ProductTagSelectionComponent`	Searching and selecting products to tag (up to 20 in livestream mode)	iOS, Android, Web
`ManageProductTagListComponent`	Managing tagged products with pin/unpin/remove (host view); browsable read-only list (viewer view)	iOS, Android, Web

The viewer sees a tag icon with a badge count. Tapping it opens a scrollable product list overlay. Tapping a product opens its link in an in-app browser while the stream continues playing.

Full component reference → Product Tagging Components · Livestream Components

Common Mistakes

Using the parent post ID instead of the child post ID — pinProduct, unpinProduct, and updateProductTags all require the child room post ID. Using the parent ID silently fails or throws an error.

Calling updateProductTags with just the new product — This is a full replacement, not an append. If you pass only the new product, all existing tags are removed. Always merge with the existing array first.

Pinning a product that isn’t in productTags — The product must already exist in the tag list. Pin it after adding it via createRoomPost or updateProductTags.

Best Practices

Merchandising strategy

Pre-tag all products before going live so they’re ready immediately
Pin the highest-margin or most-relevant product first
Swap the pinned product every 3–5 minutes to keep the showcase fresh
Remove sold-out products from the tag list in real-time

Co-host coordination

Grant product permissions to a dedicated “product manager” co-host
Have the host focus on presenting while the co-host manages pin swaps
Revoke permissions if a co-host leaves mid-stream

Analytics & optimization

Call markAsViewed when the product card enters the viewport (use intersection observer on Web)
Call markAsClicked on tap/click before opening the product URL
Review view-to-click ratios in the Admin Console to optimize product placement
A/B test pin timing to find the optimal pin duration per product category

Next Steps

Go Live & Room Management

Room creation, broadcast setup, and lifecycle management.

Co-Hosting

Invite co-hosts to share the stage during a broadcast.

Live Chat & Engagement

Wire up chat, reactions, and viewer count alongside the video.

Overview

Build Your Community

Create & Share Content

Communication

Engage & Grow

Livestream

Monetize

How Product Tagging Works

Admin Console: Set Up Your Product Catalogue

In-App: Tag & Pin Products

Tag products

Manage tagged products

Viewer experience

Step-by-Step Implementation

UIKit: Pre-Built Product Tagging Components

Common Mistakes

Best Practices

Next Steps

Go Live & Room Management

Co-Hosting

Live Chat & Engagement

​How Product Tagging Works

​Admin Console: Set Up Your Product Catalogue

​In-App: Tag & Pin Products

Tag products

Manage tagged products

​Viewer experience

​Step-by-Step Implementation

​UIKit: Pre-Built Product Tagging Components

​Common Mistakes

​Best Practices

​Next Steps

Go Live & Room Management

Co-Hosting

Live Chat & Engagement

How Product Tagging Works

Admin Console: Set Up Your Product Catalogue

In-App: Tag & Pin Products

Viewer experience

Step-by-Step Implementation

UIKit: Pre-Built Product Tagging Components

Common Mistakes

Best Practices

Next Steps