Skip to main content
SDK v7.x · Last verified March 2026 · iOS · Android · Web
import { PostRepository } from '@amityco/ts-sdk';

// 1. Text post with product tags
const textPost = await PostRepository.createPost({
    targetType: 'community',
    targetId: communityId,
    dataType: 'text',
    data: { text: 'Loving this Nike Air Max for my morning runs!' },
    productTags: [
        { productId: 'prod_001', text: 'Nike Air Max', index: 12, length: 12 },
    ],
});

// 2. Image post with attachment product tags
const imagePost = await PostRepository.createPost({
    targetType: 'community',
    targetId: communityId,
    dataType: 'image',
    data: { text: 'Check out these products!' },
    attachments: [
        { fileId: 'image-file-id-1', type: 'image' },
        { fileId: 'image-file-id-2', type: 'image' },
    ],
    attachmentProductTags: {
        'image-file-id-1': [{ productId: 'prod_001' }],
        'image-file-id-2': [{ productId: 'prod_002' }],
    },
});

// 3. Track engagement
product.analytics.markAsViewed('feed_page/product_list/product_item', 'post', postId);
product.analytics.markAsClicked('feed_page/product_list/product_item', 'post', postId);
Full walkthrough below ↓
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 section.
Post composer showing product tag dropdown with Radiant Glow Vitamin C Elixir and Radiant Brightening Citrus Serum results
Product tagging lets users attach products from your catalogue to posts and livestreams, turning social content into a shoppable storefront. Viewers see product cards with images, prices, and direct links — without leaving the feed or stream.

​
Where Product Tagging Works

Content typeTag mechanismMax tagsPinningPlatforms
Text postproductTags — reference product by position in text20—iOS, Android, Web
Image postattachmentProductTags — link products to specific images by fileId20—iOS, Android, Web
Video postattachmentProductTags — link products to specific videos by fileId20—iOS, Android, Web
LivestreamproductTags + pinnedProductId on room post201 at a timeiOS, Android, Web
Flutter and React Native do not yet support product tagging.

​
Step 0: Set Up Your Product Catalogue

Before any tagging can happen, products must exist in Admin Console → Product catalogue.
1

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
2

Add products individually or in bulk

Click + Add product to create one product at a time, or use Import to upload a CSV for bulk creation. Each product needs:
  • Product ID — unique identifier (cannot change after creation)
  • Product Name — display name shown when tagged
  • Product URL — link for viewers to click through
  • Status — must be Active to appear in tag search
Admin Console Add Product form with Product ID, Status, Product name, Product URL, Price, and image upload fields
3

Verify Active status

Only Active products are discoverable in the tag-product search. Set seasonal or discontinued products to Archived to hide them without deleting.
Full Admin Console guide → Product Catalogue

​
Tag Products in Posts

The post composer includes built-in product tagging — type @ and switch to the product tab:

Tag products while composing

Post composer showing @ trigger with product tag tab and product results

Tagged products displayed below the post

Products tagged in this post bottom sheet showing Radiant Glow Vitamin C Elixir ($32) and Serum CitrusGlow Brightening ($32)
UIKit components used:
ComponentRole
ProductTagSelectionComponentSearch and multi-select products (mode: create, edit, or livestream)
ProductTagListComponentRead-only list below the post (mode: post, image, video, livestream)
Component reference → Product Tagging Components

​
SDK: Text Post with Product Tags

Tag products inline within the text. Each tag references a product by ID and a position range in the text. 
const post = await PostRepository.createPost({
    targetType: 'community',
    targetId: communityId,
    dataType: 'text',
    data: { text: 'Loving this Nike Air Max for my morning runs!' },
    productTags: [
        { productId: 'prod_001', text: 'Nike Air Max', index: 12, length: 12 },
    ],
});

​
SDK: Image Post with Attachment Product Tags

For image (and video) posts, attach products to specific media files using attachmentProductTags. Products are linked by the fileId of each uploaded image. 
const post = await PostRepository.createPost({
    targetType: 'community',
    targetId: communityId,
    dataType: 'image',
    data: { text: 'Check out these products!' },
    attachments: [
        { fileId: 'image-file-id-1', type: 'image' },
        { fileId: 'image-file-id-2', type: 'image' },
    ],
    attachmentProductTags: {
        'image-file-id-1': [{ productId: 'prod_001' }],
        'image-file-id-2': [{ productId: 'prod_002' }],
    },
});
SDK reference → Text Posts · Image Posts · Video Posts

​
Tag Products in Livestreams

Livestream product tagging adds pinning — the host (or authorized co-host) can pin one product at a time as a prominent overlay visible to all viewers.

Host view — pinned product overlay

Livestream with a pinned product card (GlowLab Soft Glow Blush Stick, $24) at the bottom and Unpin button

Viewer view — scrollable product list

Products tagged bottom sheet with pinned product at top, View buttons, and scrollable list

​
Key differences from post tagging

CapabilityPostsLivestreams
Pin a product as overlay—✅ (1 at a time, auto-replaces)
Swap pin mid-session—✅
Co-host product permissions—✅ (host grants per co-host)
Update tags after creation✅✅ (full replacement)
Viewer click-through✅✅ (in-app browser, stream continues)
Full livestream product tagging walkthrough → Livestream: Product Tagging

​
Manage tagged products during the stream

ManageProductTagListComponent showing pinned product at top, other products with Pin and Delete buttons, and Add products button

​
Track Product Engagement

Both post and livestream product tags support fire-and-forget analytics for views and clicks. Events are automatically deduplicated per product per source. 
// When a product card enters the viewport
product.analytics.markAsViewed(
  'feed_page/product_list/product_item',   // location
  AnalyticsSourceTypeEnum.POST,             // or ROOM for livestreams
  postId,                                   // source ID
);

// When a viewer taps the product link
product.analytics.markAsClicked(
  'feed_page/product_list/product_item',
  AnalyticsSourceTypeEnum.POST,
  postId,
);
EventDeduplication keyNotes
markAsViewed{productId}.view.{sourceType}.{sourceId}Same product in different posts = separate events
markAsClicked{productId}.linkClicked.{sourceType}.{sourceId}Fire before opening the product URL

​
Admin Console: Review product performance

Tagged posts surface in the console with linked product cards — admins can see which products are referenced and filter posts by tag.
Admin Console post list showing posts with product tags including thumbnails and product names

​
Posts vs. Livestreams: Choosing the Right Approach

Best for: Product reviews, influencer recommendations, curated collections, community marketplaces.
  • Tag products in text, image, or video posts
  • Products appear as a “Products tagged in this post” section below the content
  • Viewers browse and click through at their own pace
  • No real-time coordination required
Best for: Flash sales, product demos, Q&A sessions, unboxing events.
  • Pin one product at a time as a prominent overlay
  • Swap pins mid-stream to match what the host is discussing
  • Co-hosts can manage products if the host grants permission
  • Pair with live chat for real-time questions about the product
Best for: Maximizing content lifespan.
  • After a livestream ends, the post remains in the feed with all tagged products still browsable
  • Viewers who missed the live event can still shop the product list
  • Pin overlay is removed in replay, but the product list persists

​
Common Mistakes

Tagging an Archived product — Only products with Active status in the Admin Console appear in the tag-product search. If a host can’t find a product, check its status.
Confusing text tags vs. attachment tags — Text posts use productTags (position in text). Image and video posts use attachmentProductTags (keyed by fileId). Mixing them up causes silent failures.
Using the parent post ID for livestream pin/unpin — pinProduct and unpinProduct require the child room post ID, not the parent. See Livestream Product Tagging for details.

​
Best Practices

  • Use CSV import for initial catalogue setup with many products
  • Use consistent Product IDs (e.g., SKU-001) — they’re immutable after creation
  • Archive seasonal products instead of deleting to preserve tag history
  • Keep thumbnails at 1:1 aspect ratio for consistent display
  • Tag 3–5 products per post for best engagement — too many dilutes focus
  • For livestreams, pre-tag all products before going live so they’re ready immediately
  • In image posts, link each product to the specific image that shows it
  • Use text tags for editorial posts, attachment tags for visual-first content
  • Call markAsViewed when the product card enters the viewport (use intersection observer on Web)
  • Call markAsClicked on tap before opening the URL
  • Review view-to-click ratios in the Admin Console to optimize product placement
  • A/B test text tags vs. attachment tags to see which drives more clicks

Livestream Product Tagging

Deep-dive: pin/unpin, co-host permissions, and per-stream analytics.

Rich Content Creation

Text, image, video, poll, and file posts with @mentions and hashtags.

Product Catalogue (Console)

Admin guide for uploading, importing, and managing your product database.

UIKit Components

ProductTagSelectionComponent, ProductTagListComponent, and ManageProductTagListComponent.

Text Post SDK

productTags parameter reference for text posts.

Video SDK Product Tagging

Room post creation, pinProduct, unpinProduct, and co-host permissions.