# tt-blocks Docs (full content) > Full documentation content for LLM consumption. Each section corresponds to one page; pages are separated by horizontal rules. # TT Badges & Product Labels URL: https://docs.tantou.ai/tt-blocks/ Description: A no-code visual block app for Shopify merchants — badges, buttons, coupons, brand icons, product labels, and more. Last updated: 2026-05-08T02:02:35.000Z **TT Badges & Product Labels** is a no-code visual app for Shopify merchants. Build storefront content blocks (trust badges, buttons, coupons, brand icons, product image labels, and more) through the admin editor and wizard, and control exactly which pages and visitors see each block. **[→ Install on the Shopify App Store](https://apps.shopify.com/tt-trust-badges-and-icons)** ![a storefront collage showing typical TT Badges & Product Labels blocks in action — product-page badges, floating brand icons, cart coupon, footer trust badges](https://static.tantou.ai/images/tt-blocks/2026/05/a24a8195185e7b43.png) ## What problem it solves Adding storefront content blocks usually means editing theme Liquid or installing several single-purpose apps. TT Badges & Product Labels bundles **visual component editing + display rules + localization** into one app, so merchants can: - Avoid theme code — blocks inject through a Theme App Extension - Cover badges / buttons / coupons / brand icons / payment icons / product labels in a single app - Use 8 visibility dimensions (pages / products / variants / customers / location / device / schedule / UTM) to control exposure - Auto-switch translations by Shopify locale ## Typical use cases | Scenario | What to use | |:--|:--| | Product-page trust badges ("7-day no-fuss returns" / "Authentic guarantee") | Trust Hero / Trust Marquee templates | | Cart-page coupon prompt that auto-copies into checkout | Coupon component + cart placement | | Footer row of Visa / Mastercard payment icons | Payment Icons component + footer placement | | Floating WhatsApp / WeChat contact cluster in the bottom-right | Floating Icons + messaging preset | | Product-image labels like "Sale 25%" / "New" | Label block + 4 built-in presets | | Scheduled 11.11–11.13 promo that auto-publishes / expires | Schedule dimension + time window | ## Components 11 component types, used standalone or composed: - **Heading** / **Text** - **Button** / **Button List** - **Badge** / **Badge List** - **Brand Icon** (item) / **Brand Icons** (container) - **Payment Icons** - **Coupon** - **Label chip** (product-image only) See [Components](/tt-blocks/components/badge). ## Block types Three behavior modes, derived from [placement](/tt-blocks/reference/placement-modes): - **Complex** — product page / cart / footer / other concrete placements (most common) - **Floating** — viewport-edge floating - **Label** — product-image overlay See [Block types](/tt-blocks/concepts/widget-types). ## Free vs Pro Free covers unlimited blocks, all 11 component types, all 7 placements, basic visibility rules, and a 5-product demo of **Specific products**. Pro unlocks advanced filters (Products / Variants / Customers), Country / Schedule / UTM targeting, **Hide theme elements**, and per-block **Advanced CSS**. Full comparison: [Plans and pricing](/tt-blocks/plans). ## Recommended reading path 1. [Install and enable](/tt-blocks/getting-started/install) — from App Store install to enabling the theme app embed 2. [Quick start](/tt-blocks/getting-started/quick-start) — 10 minutes through the basics 3. [Block creation wizard](/tt-blocks/wizard) / [Editor overview](/tt-blocks/editor/overview) — go deeper If you're specifically building product-image labels, jump to [Quick start (label)](/tt-blocks/getting-started/quick-start-label). --- # Changelog URL: https://docs.tantou.ai/tt-blocks/changelog/ Description: TT Badges & Product Labels version history. Last updated: 2026-05-08T02:18:03.000Z > Versions follow [semantic versioning](https://semver.org/). Format follows [Keep a Changelog](https://keepachangelog.com/). ## v1.0.0 — Initial release First public release, covering the following capabilities: ### Widget types - **Complex** — mounts to concrete placements (product page / cart / footer / …) - **Floating** — viewport-edge floating (top / bottom / left / right) - **Label** — product-image overlay chip ### Components Heading / Text / Button / Button List / Badge / Badge List / Brand Icons / Payment Icons / Coupon / Label. ### Editor - 4 tabs: Content / Design / Display / Localization - Real-time canvas preview (iframe + postMessage) - Desktop / mobile responsive preview toggle ### Display rules - 8 independent visibility dimensions: pages / products / variants / customers / location / device / schedule / UTM (Pro) — plus Placement and Hide theme elements as SubNav entries (not dimensions) - Real-time validation via the Simulator sidebar ### Color schemes & themes - 5 built-in color schemes - Theme-derived color schemes from your Shopify theme ### Localization - Per-language translations in the editor; the storefront switches by buyer locale ### Plans - Free + Pro tiers (see [Plans and pricing](/tt-blocks/plans)) --- # Badge URL: https://docs.tantou.ai/tt-blocks/components/badge/ Description: Single badge component with icon / shape / popover. Last updated: 2026-05-07T04:59:23.000Z **Badge** (type: `badge`, display name **"Badge"**). Often used on product pages to highlight selling points, certifications, warranty info, etc. Can be used standalone or inside a [Badge list](/tt-blocks/components/badges) container. ![storefront badge rendering (default + hover / popover state)](https://static.tantou.ai/images/tt-blocks/2026/05/918669f6c738df4d.png) ## Fields ### Text - **Title** — main title - **Subtitle** — subtitle ### Image (toggle on) Icon picker (tabs: **Icons** / **Brand** / **Payment** / **Shapes** / **URL**) + the following controls: - **Icon size** — slider 10–100% - **Color** - **Hover animation** Icon variants: - Shape weights: **Regular** / **Thin** / **Filled** / **Duotone** - Brand variants: **Color** / **Mono** ### Shape (toggle on, only when Image is on) Shape picker + the following controls: - **Color** - **Hover animation** - **Border**: color / opacity / width ### Popover (toggle on) - **Trigger**: **Click** / **Hover** - **Popover title** (placeholder **"Enter your title"**) - **Popover description** — multi-line (placeholder **"Enter your description"**) - **Popover link text** + **Popover link URL** ![Badge editor sections (collapsed + fully expanded)](https://static.tantou.ai/images/tt-blocks/2026/05/3b7184393446dc6b.png) --- # Badge list URL: https://docs.tantou.ai/tt-blocks/components/badges/ Description: Multi-badge container component, displays badges in a row. Last updated: 2026-05-07T04:59:23.000Z **Badge list** (type: `badge_list`, display name **"Badges"**) is a container component holding multiple [Badge](/tt-blocks/components/badge) children with unified layout and styling. ![storefront badge list rendering (multiple badges)](https://static.tantou.ai/images/tt-blocks/2026/05/d6dfb15e29b205ea.png) ## Container layout - **Direction** — **Horizontal** / **Vertical** - **Justify** — **Start** / **Center** / **End** / **Space between** / **Space around** - For column direction also: cross-axis align — **Left** / **Center** / **Right** / **Stretch** - **Gap** — child spacing 0–80 ## Image (collapsible section) Unifies all child badges' image params: - **Desktop icon size** / **Mobile icon size** — 10–200 - **Desktop gap** / **Mobile gap** — 0–100 ## Title (collapsible) - **Desktop font size** / **Mobile font size** - **Color** ## Subtitle (collapsible) - **Desktop font size** / **Mobile font size** - **Color** ## Card mode (toggle on) **"Wrap each child in a card"**: - **Card background** - **Card border**: color / opacity / width - **Card radius** - **Card padding** ## Other - **Hover animation** - **Spacing** — responsive **Padding** / **Margin** ![Badge list editor sections](https://static.tantou.ai/images/tt-blocks/2026/05/a7356f75ca36a6fd.png) ## Children Child editing: see [Badge](/tt-blocks/components/badge). --- # Brand icon (item) URL: https://docs.tantou.ai/tt-blocks/components/brand-icon/ Description: Single brand icon item (type: brand_icon), used as a child of brand icon container. Last updated: 2026-05-07T04:59:23.000Z **Brand icon** (type: `brand_icon`, display name **"Brand icon"**). **Used as a child of [Brand icons](/tt-blocks/components/brand-icons) container** — not added directly as a top-level component. > i18n's `type.brand_icon` (singular) and `type.brand_icons` (plural container) share the same display name — merchants don't see this distinction in the admin, only the container and its children. ## Fields ### Source - **Icon library** (`brand` for e-commerce / `social` for social media / SNS / `contact` for messaging) filtered by category - After selecting a brand, the corresponding R2 resource is auto-loaded ### Variant - **Color** (`color`) — official brand color - **Mono** (`mono`) — black & white version ### Link - **Link** — URL - **Target** — **Same tab** / **New tab** ### Size - Icon size follows the parent container (`brand_icons`) `desktopSize` / `mobileSize` fields uniformly ## Container relationship - `brand_icon` item fields are **child-level**: source, variant, link, target - `brand_icons` (container) fields are **container-level**: direction, alignment, gap, hover animation, card mode, unified icon size - Merchant adds the container in the editor first, then enters the container to add / edit each `brand_icon` child See [Brand icons (container)](/tt-blocks/components/brand-icons). ![brand_icon item editor panel (inside brand_icons container)](https://static.tantou.ai/images/tt-blocks/2026/05/49fe32e1c0e4fa96.png) --- # Brand icons URL: https://docs.tantou.ai/tt-blocks/components/brand-icons/ Description: Brand icon container component, displays multiple brand logos in a row. Last updated: 2026-05-07T04:59:23.000Z **Brand icons** (type: `brand_icons`, display name **"Brand icons"**) is a container holding multiple [Brand icon](/tt-blocks/components/brand-icon) children, unified layout and styling. Brand library categories include e-commerce channels, social media, SNS / messaging — see [Reference - Icon library](/tt-blocks/reference). ![Brand icons component rendered on the storefront](https://static.tantou.ai/images/tt-blocks/2026/05/3c30b29e8a177fd1.png) ## Container layout - **Direction** — **Horizontal** / **Vertical** - **Justify** — **Start** / **Center** / **End** / **Space between** / **Space around** - **Gap** — child spacing - **Desktop icon size** / **Mobile icon size** — unified for all children - **Desktop gap** / **Mobile gap** ## Style - Icon picker (tab: **Brand**); variants **Color** / **Mono** - **Link** — destination URL + **"Target"** (**Same tab** / **New tab**) ## Card mode (toggle on) - **Card background** / **Card border** / **Card radius** / **Card padding** ## Other - **Hover animation** - **Spacing** — responsive ## Children Child editing: see [Brand icon (item)](/tt-blocks/components/brand-icon). --- # Button URL: https://docs.tantou.ai/tt-blocks/components/button/ Description: Single-button component (type: button) — presets, link, styling. Last updated: 2026-05-07T04:59:23.000Z **Button** (type: `button`, display name **"Button"**). Can be used standalone or inside a [Button list](/tt-blocks/components/button-list) container. ![storefront button rendering (default + hover + click navigation)](https://static.tantou.ai/images/tt-blocks/2026/05/86a612734ebec83a.png) ## Fields ### Text - **Label** (`label`) — button text - **Font size** — responsive desktop / mobile - **Font weight** — Regular / Medium / Semibold / Bold / Extra bold / Black - **Text case** — Default / Uppercase / Lowercase ### Link - **URL type** (`url.type`): - **Static** (`static`) — direct URL (placeholder `https://shop.com/...`) - **Metafield** (`metafield`) — pick a product metafield namespace; resolves per-product (**"Pick a product metafield of type Single line text or URL."**) - **Per-product** (`products`) — multi-product map; resolves by current page product ID - **Target** (`target`): **Same tab** / **New tab** ### Style - **Background** — Fill type (solid / gradient / tricolor / pattern) - **Text color** - **Border** — color / opacity / width - **Radius** - **Padding** — responsive `{mobile, desktop}` ### Icon (toggle) - Icon picker (Icons / Brand / Payment / Shapes / URL) - Icon position (left / right) - Icon-text gap - Icon size ### Animation - **Hover animation** — multiple presets - **Button animation** (nudge) — sustained attention animation ## Three button preset categories i18n classifies built-in presets into three categories — merchants can one-click select in the wizard / editor: ### Shop (`buttonPreset.cat.shop`) - **Buy on Amazon** / **Buy on Aliexpress** / **Buy on Ebay** / **Buy on Etsy** / **Buy on Rakuten** / **Buy on Walmart** / **Buy on Yahoo! Shopping** ### Social - **Facebook** / **Instagram** / **TikTok** / **X** / **YouTube** ### Communication (`buttonPreset.cat.communication`) - **Email** / **WhatsApp** / **Messenger** / **Telegram** / **LINE** / **WeChat** / **KakaoTalk** Each preset comes with the corresponding brand's icon (color / mono variants) and default styling. After selecting a preset, the merchant can continue to edit text, link, etc. ## Relationship to button-list `button` can be used as a top-level component, or as a child of [Button list](/tt-blocks/components/button-list) (`button_list`) container, where multiple buttons share unified layout and styling. ![button editor (collapsed + fully expanded)](https://static.tantou.ai/images/tt-blocks/2026/05/c9c092eb94d5e1b6.png) --- # Button list URL: https://docs.tantou.ai/tt-blocks/components/button-list/ Description: Multi-button container component, displays buttons in a row. Last updated: 2026-05-07T04:59:23.000Z **Button list** (type: `button_list`, display name **"Button Group"**) is a container holding multiple [Button](/tt-blocks/components/button) children, unified layout and styling. ![storefront button list rendering](https://static.tantou.ai/images/tt-blocks/2026/05/93da71e6282089c1.png) ## Container layout - **Direction** — **Horizontal** / **Vertical** - **Justify** — **Start** / **Center** / **End** / **Space between** / **Space around** - For column direction also: cross-axis align - **Gap** — child spacing ## Style - **Background** (Fill type) - **Border** - **Radius** - Button preset support — see [Button](/tt-blocks/components/button) three preset categories (Purchase / Social / Contact) ## Card mode (toggle on) - **Card background** / **Card border** / **Card radius** / **Card padding** ## Other - **Hover animation** - **Button animation** (nudge) for child buttons - **Spacing** — responsive **Padding** / **Margin** ## Children Each child is a [Button](/tt-blocks/components/button) with full button fields: - **Label** — button text - **Link** — URL + **"Target"** (**Same tab** / **New tab**) - **Background** / **Text color** / **Radius** / **Padding** - **Icon** (optional, with picker) Add via **"+ Add button"** or pick from **"Button preset"** submenu (one-click insert with brand defaults). ![Button list editor sections + button preset submenu](https://static.tantou.ai/images/tt-blocks/2026/05/b859c61d2efd61a4.png) --- # Coupon URL: https://docs.tantou.ai/tt-blocks/components/coupon/ Description: Display a copyable coupon code with label + discount code + expiration. Last updated: 2026-05-07T04:59:23.000Z **Coupon** (type: `coupon`, display name **"Coupon"**) displays a copyable discount code. Includes label text, discount code, and expiration time. ![storefront coupon rendering + click → copy interaction](https://static.tantou.ai/images/tt-blocks/2026/05/09a208d8fa4d4009.png) ## Fields ### Text - **Label** — coupon caption (e.g. "10% OFF") - **Code** (`code`) — the discount code value (paste from Shopify Discounts page) - **Expires at** (`expiresAt`) — optional expiration time - Tip: **"Coupon auto-hides on storefront after this time. Leave empty for no expiration."** ### Style - **Background** — Fill type - **Text color** / **Code color** - **Border** — color / opacity / width - **Radius** - **Padding** — responsive ### Icon (optional) - Icon picker - Position (left / right) ### Animation - **Hover animation** - **Button animation** (nudge) for sustained attention ## Click behavior When customers click the coupon: - Code is auto-copied to clipboard (toast: **"Copied!"**) - Simultaneously triggers `fetch("/discount/CODE", { redirect: "manual" })` to auto-apply discount - If the discount code exists in Shopify Discounts, it applies on next checkout i18n hint: **"Copied to clipboard and applied to checkout."** ## Setup flow To make the discount actually work, the merchant must first create the discount code in Shopify Admin → Discounts. Detailed flow: [Make coupon work](/tt-blocks/how-to/coupon-setup). ## Expiration behavior After `expiresAt` is reached: - Client `widget.js` detects current time > `expiresAt` → **the entire coupon component auto-hides** - No need for merchant to manually unpublish ![Coupon editor sections](https://static.tantou.ai/images/tt-blocks/2026/05/5c45883e525ac928.png) --- # Group URL: https://docs.tantou.ai/tt-blocks/components/group/ Description: Generic grouping container (type: group). Last updated: 2026-05-07T05:31:49.000Z **Group** (type: `group`, display name **"Group"**) is a generic container component that wraps **heterogeneous children** into one visual unit with unified layout and styling. Difference from specialized containers (`badge_list` / `button_list` / `brand_icons` / `payment_icons`): | Container | Child type restriction | Typical scenario | |:--|:--|:--| | `group` | Any mix | Combine a heading + a row of badges + a line of text into one visual unit | | `badge_list` | Only `badge` | Multiple badges in a row | | `button_list` | Only `button` | Multiple buttons in a row | | `brand_icons` | Only `brand_icon` | Multiple brand icons in a row | | `payment_icons` | Only payment icon | Multiple payment method icons in a row | ## Fields ### Container layout - **Direction** — **Horizontal** / **Vertical** - **Justify** — **Start** / **Center** / **End** / **Space between** / **Space around** - For column direction also: cross-axis align — **Left** / **Center** / **Right** / **Stretch** - **Gap** — child spacing 0–80 ### Card mode (toggle) Wrap each child in a card style: - **Card background** / **Card border** / **Card radius** / **Card padding** ### Other - **Hover animation** - **Padding** — responsive `{mobile, desktop}` ![Group editor sections](https://static.tantou.ai/images/tt-blocks/2026/05/0fcb19a796d92ef8.png) --- # Heading URL: https://docs.tantou.ai/tt-blocks/components/heading/ Description: Heading text component. Last updated: 2026-05-08T02:18:03.000Z **Heading** (type: `heading`, display name **"Title"**) is a single-line heading text component. No margin, only padding. ![storefront heading rendering example](https://static.tantou.ai/images/tt-blocks/2026/05/01c93c196086c925.png) ## Fields ### Content - **Text** (`label`) — heading text ### Typography - **Alignment** — **Left** / **Center** / **Right** - **Font weight** — **Regular** / **Medium** / **Semibold** / **Bold** / **Extra bold** / **Black** - **Text case** — Default / Uppercase / Lowercase / Capitalize - **Font size** (`fontSize`) — responsive, max 72px, default 18px - **Desktop font size** / **Mobile font size** independent - **Font family** (`fontFamily`) — defaults to `inherit` (follows theme) ### HTML level - **Level** (`level`) — **Default (h3)** / **h1** / **h2** / **h3** / **h4** / **h5** / **h6** - Selected level affects generated HTML element (`

` ~ `

`), affecting SEO and accessibility - Default h3 avoids conflict with theme-native h1 / h2 ### Style - **Color** — with opacity, default `#1a1a1a` - **Background** (optional) — Fill type - **Border** (optional) ### Spacing - **Padding** — responsive `{mobile, desktop}` - Heading does **not** provide a margin field (rely on the container or parent container margins) ### Animation - **Hover animation** ![Heading editor](https://static.tantou.ai/images/tt-blocks/2026/05/67eaf3fc09e28142.png) ## Use suggestions - **Section heading**: h2 / h3 + bold; keep 2-4px larger than body text - **Small chip heading**: h5 / h6 + medium weight - **SEO note**: each page typically should have only one h1 — block headings should avoid h1 (default h3 is reasonable) --- # Label chip URL: https://docs.tantou.ai/tt-blocks/components/label-chip/ Description: Label component (type: label_chip), for use inside label-type blocks. Last updated: 2026-05-08T02:02:35.000Z **Label chip** (type: `label_chip`, display name **"Label"**). Exclusive to [`label`-type blocks](/tt-blocks/concepts/widget-types) (product image overlay). > Note: "Label" here refers to the chip component of label blocks, distinct from Shopify's product / customer **tag**. ## Hard binding to label block type - When `placement.auto.anchor === "label"`, the block's `content` **must be a single `label_chip` item** (audit-enforced) - Other anchors don't allow `label_chip` - Cross-type switching is hidden-prohibited (see [Block types](/tt-blocks/concepts/widget-types)) ## Fields ### Content - **Icon** (`chip.icon`) — icon picker (Icons / Brand / Shapes / URL) - **Text** (`chip.text`) — chip display text - **Content mode** (`chip.contentMode`): **Icon only** / **Text only** / **Both** (icon-only / text-only / both) - **Order** (`chip.layout.order`): **Icon first** / **Text first** - **Orientation / rotation** (`chip.orientation`) — horizontal / vertical / tilted angle ### Style - **Background** — Fill (solid / gradient / pattern) - **Text color** - **Border** - **Radius** - **Padding** - **Font size** ### Animation - **Slide entrance** — slide-in / fade-in, derived from anchor's outside edge - **Hover animation** ## v2 grouping mode A label block chip may have multiple instances at the same anchor (e.g. Sale + New on the same image). `display.grouping` controls coexistence: - **Coexist mode** — multiple chips display side by side (default) - **Standalone mode** (`standalone`) — chip exclusively occupies the anchor, hiding other coexisting chips - **Priority** — when multiple standalone chips conflict, the higher number wins; equal numbers display together (may overlap) i18n strings: - **"When multiple labels share the same anchor on an image, choose Coexist (display side by side) or Standalone (push others out)."** - **"When ON, this label exclusively occupies the current anchor and hides other coexisting labels."** - **"When multiple standalone labels are active, the higher number wins. If equal, all display together (possibly overlapping)."** ## 4 built-in presets | Key | Merchant-facing | Default conditions | |:--|:--|:--| | `label-sale` | Sale | `byCompareAtPrice` enabled | | `label-new` or `label-new-arrivals` | New arrivals | `byNewArrival.withinDays = 30` | | `label-low-stock` | Low Stock | `byInventory.threshold` enabled | | `label-natural` | Natural | No conditions, pure styling chip | See [Quick start (Product image overlay)](/tt-blocks/getting-started/quick-start-label). ## Related docs - Full label creation flow: [Quick start (Product image overlay)](/tt-blocks/getting-started/quick-start-label) - Label-type placement / scope behavior: [Block types](/tt-blocks/concepts/widget-types) --- # Payment icons URL: https://docs.tantou.ai/tt-blocks/components/payment-icons/ Description: Payment method icons group, supports manual selection or dynamic auto-detection from Shopify enabled payment methods. Last updated: 2026-05-08T02:02:35.000Z **Payment icons** (type: `payment_icons`, display name **"Payment icons"**) displays the shop's supported payment methods. Can be specified manually or auto-inferred (**Dynamic** mode). ![storefront payment icons rendering (multiple methods in a row)](https://static.tantou.ai/images/tt-blocks/2026/05/1c3b09bba1459cba.png) ## Container fields ### Icon content - **Mode toggle**: **Manual** / **Dynamic** - **Manual**: drag to reorder, **"Select icon"** opens icon picker (tab: **Payment**); merchant picks which payment methods to display - **Dynamic**: **"Auto-display payment methods enabled in your Shopify store."** ### Dynamic mode When `payment_icons.mode === "storefront"` (i18n display name **"Dynamic"**): - System reads Shopify `shop.enabled_payment_types` (injected as `window.__TTB_PAYMENT_TYPES__` in theme Liquid) - `widget.js` filters which payment icons to show based on this array - Auto-syncs when merchant enables / disables payment methods in Shopify backend So when a merchant enables Apple Pay, Visa, Mastercard, PayPal in Shopify Settings → Payments, the block auto-displays those 4 icons — no need to re-select in TT Badges & Product Labels editor. ![dynamic mode rendering (same block displays different methods per shop)](https://static.tantou.ai/images/tt-blocks/2026/05/fafad72e90583e6e.png) ### Variant rules (icon style) **Icon style** (variant, i18n `iconStyle`): | Variant | Meaning | |:--|:--| | **Color** (`color`) | Each method's official brand colors | | **Dark** (`dark`) | Light-on-dark icons for dark backgrounds | | **Light** (`light`) | Dark-on-light icons for light backgrounds | | **Mono** (`mono`) | Black & white monochrome icons | Each variant maps to different R2 icon resources. Once a variant is selected, all payment icons switch uniformly. Some brands only have partial variants (e.g. some card networks lack a dark variant); falls back to color when missing. ### Card mode (optional) - **Icon color** — toggle + **Border color** - **"Wrap each child in a card"** + Card background / Card border / Card radius ### Layout - **Direction** — **Horizontal** / **Vertical** - **Justify** - **Desktop icon size** / **Mobile icon size** - **Desktop gap** / **Mobile gap** - **Radius** ### Other - **Hover animation** - **Spacing** — responsive ![Payment icons editor (manual + dynamic mode each)](https://static.tantou.ai/images/tt-blocks/2026/05/2c87e43756a5f6b6.png) ## Relationship to other components - **Children editing**: dynamic mode has no children editing (auto-renders per `__TTB_PAYMENT_TYPES__`); manual mode allows drag-reorder + delete individual items - Difference from [Brand icons](/tt-blocks/components/brand-icons): `brand_icons` is typically social / marketing brands (Instagram / TikTok etc.), `payment_icons` is specifically payment methods (Visa / PayPal etc.), different R2 resource categories --- # Text URL: https://docs.tantou.ai/tt-blocks/components/text/ Description: Free-form text component. Last updated: 2026-05-07T04:59:23.000Z **Text** (type: `text`, display name **"Text"**) is a single / multi-line free-form text component, used for subtitles, supplementary descriptions, disclaimers, etc. ![storefront text rendering example](https://static.tantou.ai/images/tt-blocks/2026/05/d0a81c8dfef157ac.png) ## Fields ### Content - **Text** (`label`) — text content (multi-line + simple inline format supported) ### Typography - **Alignment** — **Left** / **Center** / **Right** - **Font weight** — **Regular** / **Medium** / **Semibold** / **Bold** / **Extra bold** / **Black** / **Off** - **Text case** — Default / Uppercase / Lowercase / Capitalize - **Font size** (`fontSize`) — responsive 8–80px, default 14px - **Desktop font size** / **Mobile font size** independently configurable - **Line height** (`lineHeight`) — responsive - **Font family** (`fontFamily`) — defaults to `inherit` (follows theme), merchant can explicitly specify ### Style - **Color** — with opacity (RGBA / hex), default `#333333` - **Background** (optional) — Fill type - **Border** (optional) — color / width - **Radius** — only effective when background or border is enabled ### Spacing - **Padding** — responsive `{mobile, desktop}` - **Margin** — responsive `{mobile, desktop}` ### Animation - **Hover animation** ![Text editor sections (collapsed + fully expanded)](https://static.tantou.ai/images/tt-blocks/2026/05/144bd699b788b121.png) ## Use suggestions - **Subtitle**: place below [Heading](/tt-blocks/components/heading) for supplementary description - **Disclaimer text**: thin font + light color (e.g. `#666666`) for auxiliary info - **Multi-language**: fill translations per locale in [Languages tab](/tt-blocks/editor/localization) --- # Block types URL: https://docs.tantou.ai/tt-blocks/concepts/widget-types/ Description: Three block types (Complex / Floating / Label) — what each is for and why type is locked after creation. Last updated: 2026-05-08T02:41:43.000Z Blocks come in three types depending on where you place them. **Type is not a separate field you pick** — it follows from the [placement](/tt-blocks/reference/placement-modes) you choose. Pick a placement and the type is decided for you. ## The three types | Type | Where you'd use it | Typical content | |:--|:--|:--| | **Complex** | Anchored on a product page, cart, footer, or other in-page location | Trust badges, coupons, button groups — most cases | | **Floating** | Pinned to a viewport edge (top / bottom / left / right) and stays as the visitor scrolls | Quick-link icons, support buttons, sticky promos | | **Label** | Overlaid on product images (product detail page and collection cards) | Small chips like **"Sale 25%"**, **"New"**, **"Limited"** | ## How types differ | Aspect | Complex | Floating | Label | |:--|:--|:--|:--| | Mounts on | A theme element you anchor it to | The viewport itself (fixed position) | Product image | | Number of components | Multiple, in any layout | Multiple, in any layout | One label chip per block | | Editor experience | Component list editor | Component list editor | Anchor picker + single-chip editor | | Target tab dimensions | Full 8 visibility dimensions | Full 8 visibility dimensions | 8 dimensions + a **scope** control (PDP / Cards / Both) | ## Type cannot change after creation The editor does not let you switch a block between Label and non-Label. The two are structurally different (Label holds exactly one chip on a product image; Complex / Floating can hold an arbitrary component tree), so an automatic conversion would risk losing your data. Saves and duplications that try to cross types are rejected on the server. To change type → **create a new block**. Duplicating across types is also disallowed. ## Wizard prevents type-incompatible templates When you pick a placement in the wizard, the template list auto-filters to templates compatible with that placement. Submitting an incompatible template is also rejected on the server, in case the filter was bypassed. --- # Block list URL: https://docs.tantou.ai/tt-blocks/dashboard/ Description: Grid / list views, statistics, bulk actions, setup guide. Last updated: 2026-05-08T02:02:35.000Z The default page after installing the app, titled **"Blocks"**. Centralized management of all blocks in your store. ![Block list full view with setup guide, stats row, view toggle, and grid items](https://static.tantou.ai/images/tt-blocks/2026/05/2975303e09c30fcd.png) ## Header - Page title: **"Blocks"** - Primary action: **"Create block"** button → [Block creation wizard](/tt-blocks/wizard) ## Setup guide (conditional) Shown when install steps are incomplete. The **"Setup Guide"** card: - Subtitle: **"Follow these steps to start using Tantou blocks."** - Progress: **"{done} / {total} steps completed"** - 4 steps: **"Activate app embed in Shopify"** → **"Create your first block"** → **"Add a block to your theme (optional)"** → **"Confirm your block is working on the storefront"** - **"I have done it"** / **"Skip step"** / **"Dismiss setup guide"** ![Setup guide card with 4-step progress](https://static.tantou.ai/images/tt-blocks/2026/05/a7937c424c05c141.png) ## StatsRow Four cards: - **"Published"** count - **"Not published"** count - **"Block views"** (**"Last 30 days"**) - **"App status"** — **"Active"** / **"Inactive"** - **"Active"** description: **"App embed is active — published blocks should be visible on the storefront."** - **"Inactive"** description: **"App embed is disabled. Blocks will not render on the storefront until enabled."** + **"Activate"** button ![Stats row with Disabled app status highlighted](https://static.tantou.ai/images/tt-blocks/2026/05/6ad5949d13bfc70a.png) ## View toggle Top-right **"Grid"** / **"List"** toggle. ## Grid view Four-column responsive layout. Each card: - Live block preview (200px tall, interactive) - Name (bold) + status badge (**"Published"** / **"Not published"** / **"Pending"** / **"Error"** / **"Custom"** / **"Scheduled"** / **"Expired"** / **"Hidden"**) + ⋯ menu - Placement label - Stats row: **"{n} views"** · **"{n} clicks"** · **"Last 30 days"** - **"Copy ID"** button (tooltip: **"Copy this block's ID for the theme editor"**) - **"Add to theme"** button (tooltip: **"Open the theme editor with this block pre-selected"**, opens theme location picker: **Home** / **Product page** / **Collection page**) - ⋯ menu: **Edit** / **Rename** / **Duplicate** / **Delete** ![Grid view with multiple block cards plus a single card detail](https://static.tantou.ai/images/tt-blocks/2026/05/77377824b03d200b.png) ## List view Header columns: **Name** / **Placement** / **Stats** / **Status** / **Actions** Row interaction: drag to reorder, checkbox to bulk-select. Bulk actions bar (shown when selecting): - **"{n} selected"** - **"Publish"** / **"Unpublish"** buttons - More Actions: **Duplicate** / **Delete** Row ⋯ menu: **Edit** / **Rename** / **Duplicate** / **Copy ID** / **Delete** ![List view with bulk-selection bar active](https://static.tantou.ai/images/tt-blocks/2026/05/e2576ecfd5a16b6e.png) ## Empty state Shown when no blocks exist: - Title: **"Create your first block"** - Description: **"Build blocks with headings, buttons, text, and images — they render directly in your store theme."** - **"Create block"** button ![Empty state prompting first block creation](https://static.tantou.ai/images/tt-blocks/2026/05/e9908c0633c6f29a.png) ## Dialogs - **"Rename block"**: title + text input + **"Save"** / **"Cancel"** - **"Delete block"** confirmation: **"Are you sure you want to delete \"{name}\"? This action cannot be undone."** + **"Delete"** / **"Cancel"** - Bulk delete confirmation: includes count Success toasts: - **"Block deleted"** - **"Block renamed"** - **"Block saved"** - **"Block duplicated"** - **"Copied!"** / **"Block ID copied! Paste it into the theme block settings."** ![Rename, delete, and bulk-delete confirmation dialogs](https://static.tantou.ai/images/tt-blocks/2026/05/91f6f7643822cc49.png) --- # Content tab URL: https://docs.tantou.ai/tt-blocks/editor/content/ Description: Edit the block's component tree and fields; layered drill-in by component type. Last updated: 2026-05-08T02:02:35.000Z The **"Content"** tab is layered navigation: component list → container children → single child editing. Click items to drill in; back arrow returns one level. ![Content tab three views side by side (component list, container children, single item editor)](https://static.tantou.ai/images/tt-blocks/2026/05/b5255617d0264721.png) ## View 1: Component list (outermost) The default view when opening a block — lists all top-level components. Controls: - Top heading: **"Components"** - Component cards (drag to reorder): icon + name + **"Hide"** / **"Show"** + **"Duplicate"** + **"Delete"** - Empty state: **"No components"** - **"+ Add item"** button (dashed) → popup menu in two groups: - **"Components"**: single component types (**Heading** / **Text** / **Button** / **Coupon** / **Payment icons** / **Badge**) - **"Groups"**: container types (**Buttons** / **Badges** / **Brand icons** / **Payment icons**) - Bottom **Block settings**: **"Background"** / **"Padding"** / **"Margin"** / **"Radius"** / **"Display animation"** / **"Spacing"** ![Component list view with Add item popup menu open](https://static.tantou.ai/images/tt-blocks/2026/05/9907be4273341cd8.png) ## View 2: Container children Click a container component (**Badge list** / **Button list** / **Brand icons** / **Payment icons**) to enter. Controls: - Top: back + container name (uppercase) + **"Hide"** / **"Delete"** - Container layout params (**"Direction"** / **"Gap"**, etc., per container type) - Child cards list (draggable): icon + label + **"Hide"** / **"Duplicate"** / **"Delete"** - Add buttons (per container type): - **"+ Add badge"** / **"+ Add button"** / **"+ Add icon"** - Multi-type containers: cascading menu picks subtype (**Button list** also has **"Button preset"** submenu) - **Brand icons**: opens icon picker to choose brand ![Container children view with the add child menu open](https://static.tantou.ai/images/tt-blocks/2026/05/086abb429f72f429.png) ## View 3: Single item editing Click a specific child to enter the field editor. Fields differ per type — see each [component documentation](/tt-blocks/components/badge). Some component types without an editor display: **"This component type has no editor."** ![Single child item field editor](https://static.tantou.ai/images/tt-blocks/2026/05/16f5826be2c95b3f.png) --- # Advanced tab URL: https://docs.tantou.ai/tt-blocks/editor/design/ Description: Color scheme, custom CSS, and delete actions for a block. Last updated: 2026-05-08T02:18:03.000Z The **"Advanced"** tab controls a block's overall visual style and advanced operations. ![Advanced tab overall layout](https://static.tantou.ai/images/tt-blocks/2026/05/5485effc847fbb1a.png) ## Color scheme - Card title: **"Color scheme"** - Current scheme name (custom shows **"Custom"**) - **"Change scheme"** / **"Pick a scheme"** button → opens modal: - Title: **"Color scheme"** - Top banner: **"Switching applies the chosen scheme's colors and shapes to your block. Text content, layout, and items stay as-is."** - 4 built-in schemes: **Plain Color** / **Plain Mono** / **Brand on White** / **Brand Fill** - Current scheme marked **"Current"**, after applying shows **"Applied"** When you switch a scheme, only colors and shapes change. Fields you've manually overridden stay as-is, and text / layout / items are never touched. ![Color scheme card with switch modal open](https://static.tantou.ai/images/tt-blocks/2026/05/3229321a6eafdf7e.png) ## From your theme Below the built-in schemes, the **"From your theme"** group lists schemes derived from your published storefront theme — full flow and empty-state behavior: [Apply theme colors to blocks](/tt-blocks/how-to/import-theme-colors). ## Advanced CSS (Pro) - Card title: **"Advanced CSS"** + Pro badge - Description: **"Add custom CSS for this block and other page elements."** - Multi-line CSS input, label **"Custom CSS"** The placeholder shows a starting selector tailored to the block type, ready to copy: | Block type | Starting selector | |:--|:--| | **complex** | `.widget-root { /* your styles */ }` | | **floating** | `.widget-root.floating-top { /* ... */ }` | | **label** | `.widget-label-chip { /* ... */ }` | The hint area shows extended selector examples (hover state, sub-component level, page-specific level, etc.). Non-Pro users see the locked state with an upgrade prompt. ![Advanced CSS card in collapsed, expanded, and Pro-locked states](https://static.tantou.ai/images/tt-blocks/2026/05/bcc32a36cba3277f.png) ## Delete - Card title: **"Delete"** - Tip: **"Deleting this block cannot be undone."** - **"Delete"** button (destructive style) → confirms with **"Delete this block?"** ![Delete card with confirmation modal](https://static.tantou.ai/images/tt-blocks/2026/05/a6126092f307552d.png) ## Related - Apply your storefront theme's colors to a block → [Apply theme colors to blocks](/tt-blocks/how-to/import-theme-colors) --- # Target tab URL: https://docs.tantou.ai/tt-blocks/editor/display/ Description: Control where the block is shown. 8 independent visibility dimensions, ALL must match. Last updated: 2026-05-08T02:02:35.000Z The **"Target"** tab uses 8 independent visibility dimensions to decide whether the block renders. All dimensions are **AND**: every dimension must match for the block to appear. Subtitle: **"Targeting"** / **"Only show this block when all conditions match."** ![Target tab overall layout with left SubNav, middle detail panel, right Simulator sidebar](https://static.tantou.ai/images/tt-blocks/2026/05/0993684202010c4a.png) ## SubNav (10 entries) Left SubNav lists 10 entries: **Placement** (where it mounts) + 8 visibility dimensions + **Hide theme elements** (cleanup helper). Visibility dimensions are AND-evaluated; Placement and Hide theme elements are not part of the AND. ### Placement (mount target) Not a visibility rule — it controls where the block mounts, not whether it shows. - Subtitle: **"Choose where the block appears on the storefront."** - Main dropdown: **"Where should this block appear?"** (**Storefront** / **Checkout**) - **"How is it placed?"** (**Automatic** / **Manual (theme block)**) - **"Position"** select (varies by mode) — 7 cards, see [Placement modes](/tt-blocks/reference/placement-modes) - **Custom position** mode: shows block ID + embed code + **"Add to theme"** jump - Checkout tip: **"Enable the block in the Shopify checkout editor. Shopify allows at most one checkout block per shop."** ## 8 visibility dimensions ### 1. Pages - Subtitle: **"Restrict to specific page types."** - All / Custom toggle - Custom: checkboxes - **Home (/)**, **Product (/products/...)**, **Collection (/collections/...)**, **Blog (/blogs/...)**, **Article (/blogs/.../...)**, **Cart (/cart)**, **Search (/search)**, **Page (/pages/...)**, **Password (/password)**, **404** ### 2. Products - Subtitle: **"Filter by product, collection, tag, vendor, or type."** - All / Custom toggle - **Products**: **"Include products"** / **"Exclude products"** - **Collections**: **"Include collections"** / **"Exclude collections"** - **Type** / **Vendor** / **Tags**: tag input - Free tier: max 1 product / 1 collection (demo quota) ### 3. Variants (Pro) - Subtitle: **"Match against the currently selected variant — price, inventory, options, or metafields."** - **Specific variants**: include / exclude by variant ID - **Variant price** range (in store currency) - **Variant inventory** stock-status filter - **Option rules** — by option name (Color, Size, …) and value - **Variant metafield** rules - Free tier: max 1 variant (demo quota); upgrade prompt: **"Upgrade to Pro for unlimited"** ### 4. Customers - Subtitle: **"Limit who sees this block based on login status, tags, lifetime spend, or order count."** - **Show to** (auth SegmentControl): **All visitors** / **Logged-in customers** / **Guest visitors** - When "Guest visitors" is selected, customer fields below auto-grey-out - **Tags**: tag input (**"Add tag…"**) - **By lifetime spend**: amount range (Include / Exclude) - **By order count**: number range (suffix **"orders"**) ### 5. Location - Subtitle: **"Show or hide the block by country."** - All / Custom toggle - **Countries** picker — country code (US / CA / GB) or browse, displays flags + names ### 6. Device - All / Custom toggle - Device type (SegmentControl): **Mobile** / **Desktop** - OS subset UI removed (evaluator still supports `deviceOs`, UI deferred) ### 7. Schedule - Start: **Now** / **Specific time** (12-hour time picker) - End: **Never** / **Specific time** - Timezone hint - `schedule.enabled` derived (no manual toggle needed) ### 8. UTM (Pro) - All / Custom toggle - Bulk input area (**"Browse common"** popup: utm_source / utm_medium common values checkboxes) - Standard UTM rows: source / medium / campaign / term / content (each row **Include** / **Exclude**) - Custom UTM rows: appear after fill, × to delete - **Session persistence**: landing-page UTM is stored in sessionStorage; subsequent pages read from sessionStorage as fallback (see [UTM targeting](/tt-blocks/how-to/utm-targeting)) ## Hide theme elements (Pro) Not a visibility rule — it hides existing theme elements when the block mounts (e.g. replacing the theme's sale tag). - **"Hide theme elements"**: multi-line CSS selector input (one per line, e.g. `.announcement-bar` / `#popup-overlay`) ![Visibility dimension panels assembled (Pages, Products, Variants, Customers, Location, Device, Schedule, UTM, plus Hide theme elements)](https://static.tantou.ai/images/tt-blocks/2026/05/b367326613f26c80.png) ## Numeric input tolerance Range / number inputs across dimensions have unified tolerance: - **min > max auto-swap** — reversed input is auto-corrected - **Reject negatives** — values can't be < 0 - **step 1** — integer input step ## Right Simulator sidebar Fill a virtual customer profile to preview rule matches: - Title: **"Simulated visit"** - Subtitle: **"Flip these to see how your rules would react. Does not affect the block you save."** - **"URL"** (**"Paste a real URL: page type, selected variant (?variant=N), and UTM params (utm_source / medium / campaign / …) are parsed automatically. Product pages also fetch live metafields and variants."**, placeholder `https://shop.com/products/foo?utm_source=tiktok`) - **"Device"** (SegmentControl) - **"Auth state"** (SegmentControl, **customer fields below grey out in Guest mode**) - **"Country"** (country picker, same as Location dimension) - **"Customer tags"** (**"Add tag…"**) - **"Lifetime spent ({currency})"** / **"Order count"** (suffix **"orders"**) ![Right Simulator sidebar closeup](https://static.tantou.ai/images/tt-blocks/2026/05/a1a2f2b0868e9ec7.png) --- # Languages tab URL: https://docs.tantou.ai/tt-blocks/editor/localization/ Description: Provide translations for shop's enabled locales. Last updated: 2026-05-08T02:02:35.000Z The **"Languages"** tab provides block text translations for all locales the shop has enabled. Storefront `widget.js` reads buyer's locale and applies the matching translation. ![Languages tab overall with language pills and translation table](https://static.tantou.ai/images/tt-blocks/2026/05/ee6fbdaf4bd58c0b.png) ## Layout - Top: language pills — each enabled language is one pill - Add language: **"Add language"** button → opens picker filtered to shop's enabled languages - Active language pill highlighted ## Translation table Rows = each translatable field; columns = each language. - **Field label** — common names: - Heading / Text label - Button / Coupon label - Badge title / subtitle - Popover title / description - URL field - **"Default"** column — marks which language is the default (untranslated fields fall back here) - Other language columns — fillable text inputs ![Translation table example with rows per translatable field and columns per language](https://static.tantou.ai/images/tt-blocks/2026/05/ee6fbdaf4bd58c0b.png) ## Fallback behavior Tip: **"If a language has no value, it falls back to the default language."** Storefront `widget.js`: - Reads `window.Shopify.locale` (strips region suffix, e.g. `en-US` → `en`) - Looks up translation in `config.locales[locale]` - Not found → falls back to default language ## Auto-pruning stale translation keys When a merchant deletes a component, `pruneStaleLocales` (commit `f531283`) auto-removes the corresponding translation keys from `config.locales` — preventing residue. ## Field path format Translation map keys use dotted paths: ```json "locales": { "es": { "comp_abc123.label": "Texto traducido", "comp_abc123.popover.title": "Título del popover" } } ``` Format: `.`. The runtime walks the content tree applying these per-component. --- # Editor overview URL: https://docs.tantou.ai/tt-blocks/editor/overview/ Description: The block editor's overall layout — 4 tabs + live preview + desktop / mobile toggle. Last updated: 2026-05-08T02:02:35.000Z Click a block card or list row on the home page to enter the editor — the main workspace for a single block. ![Block editor overall layout with left tabs and field panel, right live preview canvas](https://static.tantou.ai/images/tt-blocks/2026/05/cc7520ff6c7dbc50.png) ## Overall layout - **Left**: 4 tabs + field panel - **Right**: live preview canvas - A draggable splitter in between adjusts column widths ![Two-column editor layout with draggable splitter between panel and preview](https://static.tantou.ai/images/tt-blocks/2026/05/cc7520ff6c7dbc50.png) ## 4 tabs | Tab | Purpose | Details | |:--|:--|:--| | **Content** | Edit block component tree and fields | [Content tab](/tt-blocks/editor/content) | | **Design** | Color scheme (Bundle) / Custom CSS / Delete | [Advanced tab](/tt-blocks/editor/design) | | **Display** | 9-dimension display rules | [Target tab](/tt-blocks/editor/display) | | **Localization** | Multi-language text | [Languages tab](/tt-blocks/editor/localization) | ## Live preview canvas ### Render mechanism The preview canvas is an iframe loading the same `widget.js` used by the storefront. When merchants edit fields, postMessage pushes config to the iframe; Preact diff-updates inside. **Critical constraint: admin preview = storefront rendering (by construction)** — `widget.js` is a `config → DOM` pure function; admin and storefront share the same code, so what merchants see in the editor is what ships. ### Desktop / mobile toggle (viewMode) Bottom toolbar's desktop / mobile toggle buttons: - **Desktop** — canvas renders desktop fields (e.g. `desktopSize` / `desktop` padding values) - **Mobile** — canvas renders mobile fields (`mobileSize` / `mobile` padding) Mechanism: - viewMode is sent to the iframe via postMessage - WidgetRenderer uses `isMobile` context to decide which CSS each component outputs - **Does not depend** on iframe actual width (avoiding preview iframe size ≠ real device inconsistency) Production storefront: real `@media (max-width: 768px)` query. ![Live preview canvas with desktop and mobile toggle](https://static.tantou.ai/images/tt-blocks/2026/05/194f48544ef03954.png) ### Other canvas elements - **"Width"** displays current canvas width - Empty state: **"No components — add a component to start editing."** ## Top actions - Back (return to block list) - **"Undo"** / **"Redo"** (shortcuts Cmd/Ctrl+Z / Cmd/Ctrl+Shift+Z) - **"Publish"** (publishing shows **"Publishing…"**) / **"Unpublish"** (unpublishing shows **"Unpublishing…"**) - **"Copy ID"** (tooltip: **"Open this block in the theme editor and auto-add it"**) - **"Add to theme"** - **"Delete"** (tooltip: **"Deleting this block cannot be undone."**, confirm **"Delete this block?"**) New blocks default to **"My Block"** — rename via list row's **"Rename"**. ![Top action bar closeup with tabs status pill undo redo duplicate unpublish](https://static.tantou.ai/images/tt-blocks/2026/05/e82929f24eba953f.png) ## SaveBar behavior Editing any field (including placement switching → SET_PLACEMENT triggered) → top **"Save"** SaveBar appears, prompting unsaved changes. - **"Save"** — commits block config to D1 + Shopify metafield - **"Discard"** — reverts to last saved version (incl. visibility and all other fields) - Same account publishing / unpublishing in another tab → current editor's status pill auto-refreshes (BC_MSG broadcast) ## Label block special layout Label block (Product image overlay) Content tab is a dedicated panel: - **AnchorPicker** (3×3 grid) — pick chip's position on the product image - **Single LabelChip edit panel** (not a component list) - **Target tab** has an extra **scope** segmented (PDP / Cards / Both) See [Quick start (Product image overlay)](/tt-blocks/getting-started/quick-start-label) and [Block types](/tt-blocks/concepts/widget-types). --- # FAQ URL: https://docs.tantou.ai/tt-blocks/faq/ Description: Quick answers — for full procedures, follow the links to the canonical pages. Last updated: 2026-05-08T02:18:03.000Z ## Block not showing? Run through the 4-step diagnosis (app embed → placement → display rules → theme anchor). Full walkthrough: [Troubleshooting](/tt-blocks/troubleshooting). ## How does multi-language fallback work? **"If a language has no value, it falls back to the default language."** The storefront reads `window.Shopify.locale` (e.g. `en-US` → `en`) and picks up the value from the [Languages](/tt-blocks/editor/localization) tab; missing values fall back to the column marked **"Default"**. ## Will I lose my custom edits when I switch color schemes? No. **"Switching applies the chosen scheme's colors and shapes to your block. Text content, layout, and items stay as-is."** Fields you explicitly customized are snapshot-locked. ## What's the difference between Pro and Free? The main Pro-only features: **UTM traffic source**, **Hide theme elements**, **Advanced CSS**, plus the advanced filters under **Products** / **Variants** / **Customers**, **Country**, and **Schedule**. Full comparison: [Plans and pricing](/tt-blocks/plans). ## How do I uninstall? Shopify Admin → Settings → Apps and sales channels → TT Badges & Product Labels → ⋯ → **Uninstall**. Cleanup details (webhook, data deletion, theme app embed): [Install and enable](/tt-blocks/getting-started/install). ## How do I place a Custom Position block? In the editor's [Display](/tt-blocks/editor/display) tab choose **"Custom Position"**, click **"Add to theme"**, drag the manual block into your target section, then paste the block ID. Full steps: [Custom placement](/tt-blocks/how-to/custom-placement). ## Is there a block count limit? No limit on how many blocks you can create. Each block is capped at **96 KiB** of config; saving above that fails. Shopify also limits each store to one checkout block (not exposed in the current product). For the full limits table: [Reference — Data retention / limits](/tt-blocks/reference). ## My block colors don't quite match my theme In the [creation wizard](/tt-blocks/wizard) Step 3 "Style", pick a bundle from the **"From your theme"** group. If you don't see that group, your theme isn't in the supported list (vintage / fully custom themes etc.). --- # Install and enable URL: https://docs.tantou.ai/tt-blocks/getting-started/install/ Description: Install TT Badges & Product Labels from the Shopify App Store and enable the theme app embed. Last updated: 2026-05-08T02:02:35.000Z Install the app from the Shopify App Store, then enable the **app embed** in your theme so blocks can render on the storefront. After install, the home page surfaces a **"Setup Guide"** card that walks you through the 4 onboarding steps. ## Step 1 — Install from the App Store Find **[TT Badges & Product Labels](https://apps.shopify.com/tt-trust-badges-and-icons)** on the Shopify App Store and click **Add app** → confirm permissions in your admin. ![TT Badges & Product Labels on the Shopify App Store with the Add app button](https://static.tantou.ai/images/tt-blocks/2026/05/6a38b45bf1d0abc6.png) Permissions requested: - `read_locales` — read the languages enabled on your store - `read_themes` — read theme files (used to derive color schemes) - `write_products` — read products / collections / variants metafields, write block config metafields - `read_inventory` — read inventory (used by the inventory visibility dimension) - `unauthenticated_read_product_listings` / `unauthenticated_read_product_inventory` — Storefront API (used when the Label block renders on collection pages) The app does not request access to customer personal data, orders, or payment information. See [Privacy Policy](/tt-blocks/legal/privacy). ## Step 2 — Enable the app embed Step 1 of the home **"Setup Guide"**: **"Enable app embed in your Shopify theme"**. Tip: **"Enable the TT Badges & Product Labels app embed so blocks can render on your storefront."** ``` Shopify Admin → Online Store → Themes → Current theme → Customize → Theme editor bottom-left → App embeds → Toggle "TT Badges & Product Labels app embed" ON → Click Save ``` ![Theme editor App embeds panel with TT Badges & Product Labels embed toggled on](https://static.tantou.ai/images/tt-blocks/2026/05/2bfaa4ca8da891da.png) ⚠️ Note: **"Switching themes resets this toggle — you'll need to re-enable it after changing themes."** ## Step 3 — Verify Back on the TT Badges & Product Labels admin home, the **"App status"** card in [StatsRow](/tt-blocks/dashboard) should read **"Active"**. If it still shows **"Inactive"**: - Wait a few seconds and refresh (Shopify metafield sync has latency) - Confirm you actually clicked Save in the theme editor (not just toggled the switch) - Confirm you edited the published theme (not a draft theme) ![Home page App status card in the Active state](https://static.tantou.ai/images/tt-blocks/2026/05/21c8d9514927b518.png) ## Step 4 — Create your first block The setup guide then walks you through: - **"Create your first block"** — see [Quick start](/tt-blocks/getting-started/quick-start) - **"Add the block block to your product page template"** — Custom Position scenario, see [Custom placement](/tt-blocks/how-to/custom-placement) - **"Verify on your storefront"** ## Uninstall To uninstall: ``` Shopify Admin → Settings → Apps and sales channels → TT Badges & Product Labels → ⋯ → Uninstall ``` After uninstall: - Shopify automatically fires the `app/uninstalled` webhook - Merchant block data is deleted per [Privacy Policy §6](/tt-blocks/legal/privacy) - The TT Badges & Product Labels app embed in your theme is deactivated automatically (blocks no longer render on the storefront) ## Multi-store / development stores - Each Shopify store installs and is billed independently - You can install on a Shopify development store for testing (free demo mode) --- # Quick start URL: https://docs.tantou.ai/tt-blocks/getting-started/quick-start/ Description: 10 minutes through all the basics — create, edit, set display rules, translate, publish, verify. Last updated: 2026-05-08T02:02:35.000Z Run through the basic features in 10 minutes — from a fresh install to seeing a block on your storefront. Each step shows the **minimum operation** only; deep details link out to the relevant doc. ## Prerequisites Complete [Install and enable](/tt-blocks/getting-started/install). Confirm [Block list](/tt-blocks/dashboard) → StatsRow → **"App status"** shows **"Active"**. !["App status" card in "Enabled" state](https://static.tantou.ai/images/tt-blocks/2026/05/ba20b22e5fb7a65b.png) ## 8-step run-through ### 1. Create: build a block with the wizard (~1 min) Home → **"Create block"** → [wizard](/tt-blocks/wizard), three steps: 1. **Placement** → choose **Product page** 2. **Template** → pick anything from the recommended row (e.g. **Trust Hero**) 3. **Style** → keep **Default** The wizard exits straight into the editor. ### 2. Edit content: change one piece of copy (~1 min) [Content tab](/tt-blocks/editor/content) → tap any component in the list → edit the **Heading** / **Text** field → the right-side canvas updates in real time. ### 3. Switch color: try the [Advanced tab](/tt-blocks/editor/design) (~30 sec) [Advanced tab](/tt-blocks/editor/design) → **Color scheme** card → click **"Change scheme"** → pick another in the dialog (e.g. **Plain Mono**) → apply. Tip: **"Switching applies the chosen scheme's colors and shapes to your block. Text content, layout, and items stay as-is."** ### 4. Add a display rule (~1 min) [Target tab](/tt-blocks/editor/display) → left SubNav: **Pages** → switch to **Custom** → check **Product (/products/...)** (other pages won't show the block). ![Pages dimension Custom + Product checked](https://static.tantou.ai/images/tt-blocks/2026/05/090c30d9d2c006d4.png) ### 5. Verify the rule with the simulator (~30 sec) Right-side **Simulator** sidebar → **URL** field: `https://your-shop.com/products/foo` → check that the top StickyBar verdict shows **Visible**. ### 6. Add a translation language (optional, ~1 min) [Languages tab](/tt-blocks/editor/localization) → **"Add language"** → pick a language enabled on your store → fill one field's translation in the table. Untranslated fields fall back automatically (**"If a language has no value, it falls back to the default language."**). ### 7. Publish (~10 sec) Click **"Publish"** at the top of the editor. Status badge → **Published**. ### 8. Storefront verify (~1 min) Open **any product page** on your storefront (because Step 4 limited it to product pages). Confirm the block renders. ![storefront product page with the block visible](https://static.tantou.ai/images/tt-blocks/2026/05/bc2e9aafd0e44604.png) ## Next steps | Want to learn | Go to | |---|---| | Full wizard walkthrough | [Block creation wizard](/tt-blocks/wizard) | | Editor layout overview | [Editor overview](/tt-blocks/editor/overview) | | All 8 visibility dimensions | [Target tab](/tt-blocks/editor/display) | | Component types and fields | [Components](/tt-blocks/components/badge) | | Common how-to tasks | [How-to](/tt-blocks/how-to/custom-placement) | | Troubleshooting | [Troubleshooting](/tt-blocks/troubleshooting) | --- # Quick start (Product image overlay) URL: https://docs.tantou.ai/tt-blocks/getting-started/quick-start-label/ Description: 10-minute walk through the Label block — pick placement, choose preset, edit chip, set scope, publish, verify on PDP and collection page. Last updated: 2026-05-08T02:02:35.000Z **Product image overlay** (Label block) is a small chip directly overlaid on product images, working across PDP and product collection cards. This page covers Label-specific flow only; for general block onboarding see [Quick start](/tt-blocks/getting-started/quick-start). > ⚠️ **Cross-type switching is hidden-prohibited**: once you choose "Product image overlay", the block's type cannot be changed back. To change type, rebuild the block. ## Prerequisites Complete [Install and enable](/tt-blocks/getting-started/install). ## 8-step run-through ### 1. Create: build a label with the wizard (~1 min) Home → **"Create block"** → [wizard](/tt-blocks/wizard) Step 1 → pick **"Product image overlay"** card. - i18n: `placement.card.label.title` = **"Product image overlay"** - Tip: **"Pin a label to product images (PDP main image or collection card image)."** ### 2. Pick a preset (~30 sec) Step 2's recommended row shows 4 Label presets by default: - **Sale** — `label-sale-25`, defaults to `byCompareAtPrice` condition enabled - **New arrivals** — `label-new-arrivals`, defaults `byNewArrival.withinDays = 30` - **Low stock** — `label-low-stock`, defaults `byInventory.threshold` enabled - **Natural** — `label-natural`, no conditions, pure styling chip Pick one → **"Use this template"**. ### 3. Pick color scheme (~10 sec) Step 3 → pick a color scheme. **"Use this scheme"** → enters editor. ### 4. Edit chip content (~1 min) [Content tab](/tt-blocks/editor/content) shows a Label-specific panel: - Top **AnchorPicker** (3×3 grid, 9 anchor points) - Single **label_chip** edit panel (not a component list) - Fields: **chip.icon** / **chip.text** / **chip.contentMode** (`icon-only` / `text-only` / `both`) / **chip.layout.order** (`icon-first` / `text-first`) ![Label editor with AnchorPicker + single chip panel](https://static.tantou.ai/images/tt-blocks/2026/05/01c5d60c335b3399.png) ### 5. Set scope (~15 sec) [Target tab](/tt-blocks/editor/display) → top has a new **scope** segmented control: - **Page** (PDP only) - **Cards** (collection cards only) - **Both** (PDP + cards) i18n: `placement.scope.pdp` = **"Product page"** / `placement.scope.card` = **"Cards"** / `placement.scope.both` = **"All"** ### 6. Tune visibility conditions (optional, ~1 min) Label v1 surfaces 4 condition dimensions (the other 8 are evaluator-supported but UI deferred to P3): - **byCompareAtPrice** — toggle "Only on sale" - **byDiscountPercent** — min/max sliders - **byInventory** — toggle + threshold - **byNewArrival** — withinDays number If you used a preset, defaults are pre-filled — tune or accept. ### 7. Publish (~10 sec) Click **"Publish"** at the editor top. Status badge → **Published**. ### 8. Dual-scenario verify (~1-2 min) Verify based on scope configuration: | scope | Verification page | |:--|:--| | Page | Any product page | | Cards | Any collection / search / recommendation page | | Both | Both above | ![chip on PDP + chip on collection card](https://static.tantou.ai/images/tt-blocks/2026/05/4222a7769c5874a1.png) ## Next steps | Want to learn | Go to | |:--|:--| | Difference between Label and other block types | [Block types](/tt-blocks/concepts/widget-types) | | Full label_chip field set | [Label chip](/tt-blocks/components/label-chip) | --- # Make coupon work URL: https://docs.tantou.ai/tt-blocks/how-to/coupon-setup/ Description: Create discount in Shopify Admin → paste into Coupon component → click auto-copies and applies at checkout. Last updated: 2026-05-08T02:02:35.000Z The [Coupon](/tt-blocks/components/coupon) component itself only displays a code with click-copy support; for customers to actually get the discount at checkout, you must first create the discount code in Shopify Admin. i18n hint: **"Create the discount in Shopify Admin and paste it here. Click copies and applies to checkout."** ## Steps ### 1. Create discount in Shopify Admin Path: ``` Shopify Admin → Top nav → Discounts → Create discount ``` Choose discount type, fill in code value, discount amount, validity period, etc. ![Shopify Discounts page + Create discount form](https://static.tantou.ai/images/tt-blocks/2026/05/a24a8195185e7b43.png) ### 2. Copy the code value from Shopify After creation, copy the **Code** (e.g. `WELCOME20`) from the Discounts list. ### 3. Create a Coupon component in TT Badges & Product Labels editor In the [wizard](/tt-blocks/wizard) pick a "Discount" template, or in an existing block's [Content tab](/tt-blocks/editor/content) → **"+ Add item"** → Coupon. ### 4. Paste the discount code In the Coupon component's **Code** (`code`) field, paste the value from Shopify. ![Coupon editor Code field filled](https://static.tantou.ai/images/tt-blocks/2026/05/0fcb19a796d92ef8.png) ### 5. Set expiration Recommend matching the **Expires at** (`expiresAt`) field to Shopify Discounts validity period. Tip: **"Coupon auto-hides on storefront after this time. Leave empty for no expiration."** ### 6. Publish [Publish](/tt-blocks/editor/overview) the block. ### 7. Customer experience Customer clicks coupon → - Auto-copies to clipboard (toast: **"Copied!"**) - Simultaneously triggers `fetch("/discount/CODE", { redirect: "manual" })` to auto-apply discount - Discount auto-takes-effect when customer enters checkout — **no manual paste needed** ![storefront coupon rendering + click toast + applied at checkout](https://static.tantou.ai/images/tt-blocks/2026/05/bc2e9aafd0e44604.png) ## Shopify discount type compatibility Coupon component's "display + copy + apply" flow is compatible with **all Shopify discount types** (calculation handled by Shopify): | Shopify discount type | Compatible | Notes | |:--|:--|:--| | Amount off products | ✅ | Customer enters checkout, Shopify applies per rule | | Buy X get Y | ✅ | Same | | Amount off order | ✅ | Same | | Free shipping | ✅ | Same | | Automatic discount (no code needed) | ❌ | Not applicable (Coupon component is a code field; auto discount needs no code input) | ## Multiple codes per component? **Currently one Coupon component holds 1 code.** To display multiple discount codes: - Use [Button list](/tt-blocks/components/button-list) container with multiple Coupon children - Or build multiple blocks with visibility rules to display them separately ## Post-expiration behavior After `expiresAt` is reached: - Client `widget.js` detects current time > `expiresAt` → **the entire coupon component auto-hides** (code no longer shown) - No need for merchant to unpublish manually; to revoke earlier, edit the component and clear `code` or unpublish the block --- # Embed block at any theme location URL: https://docs.tantou.ai/tt-blocks/how-to/custom-placement/ Description: Custom Position flow — copy ID → theme editor → add app block. Last updated: 2026-05-08T02:02:35.000Z When the [wizard](/tt-blocks/wizard)'s 6 placement cards don't fit, choose **Custom Position** to manually place via theme editor. Tip: **"Open the theme editor and drag the block to any section."** ## Steps ### 1. Set the block to Custom Position In the [wizard](/tt-blocks/wizard) Step 1 pick **Custom Position**, or in [Target tab](/tt-blocks/editor/display) switch placement to **Custom Position**. ![wizard Step 1 Custom Position selected + editor Display switch](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) ### 2. Copy the block ID Editor top → **"Copy ID"** (tooltip: **"Copy this block's ID for the theme editor"**), or home page card ⋯ menu **"Copy ID"**. ![editor top "Copy ID" button + home page card menu](https://static.tantou.ai/images/tt-blocks/2026/05/0fcb19a796d92ef8.png) ### 3. Open theme editor Or click **"Add to theme"** to jump directly (tooltip: **"Open this block in the theme editor and auto-add it"**). !["Add to theme" button + theme editor initial view after jump](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) ### 4. Add an app block In the target section, add an app block and choose TT Badges & Product Labels. ![theme editor section's add app block popup + TT Badges & Product Labels in list](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) ### 5. Paste block ID and save Paste the block ID in the app block's settings; save the theme. ![app block settings panel + preview updates after pasting block ID](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) --- # Reuse block across multiple positions URL: https://docs.tantou.ai/tt-blocks/how-to/duplicate-widget/ Description: Duplicate existing block → change placement / display rules → publish independently. Last updated: 2026-05-08T02:02:35.000Z Reuse the same block content across multiple scenarios: duplicate, change **Placement** or **Display** rules, publish each independently. ## Steps ### 1. Find the block to reuse on the home page [Block list](/tt-blocks/dashboard) grid view or list view. ### 2. Click ⋯ → Duplicate After success, bottom-right toast: **"Block duplicated"**. ![Block list row context menu with Duplicate option highlighted](https://static.tantou.ai/images/tt-blocks/2026/05/952ba9abadd2ca48.png) ### 3. Rename Duplicate defaults to **"My Block"** — recommend immediately ⋯ → **Rename** to a recognizable name. ![Rename block modal dialog](https://static.tantou.ai/images/tt-blocks/2026/05/db22f8915cb7f561.png) ### 4. Modify duplicate's position / rules Enter the duplicate's editor: - In [Target tab](/tt-blocks/editor/display) change **Placement** or add finer rules - Content fields preserved (the point of reuse is identical content) ### 5. Publish independently The duplicate and original publish, count stats independently. ## How duplication is processed When duplicating, the system (commit `189e7a9`): 1. **Regenerates component IDs** — avoids duplicate ID conflicts with the original 2. **Remaps locales keys** — `config.locales` translation map's component ID references auto-remap to new IDs, so translations follow the duplicate 3. **Preserves all content fields** — text / heading / button preset etc. fully copied 4. **Preserves `placement`** — duplicate defaults to same placement; merchant must change manually ### What's not copied - **Block ID** (`config.key`) — regenerated - **Publish status** — duplicate defaults to **"Pending"**; needs **"Publish"** click to ship - **Historical stats** — doesn't inherit original's impression / click data; counts from 0 ### Cross-type duplication Cross-block-type duplication (e.g. duplicating a complex block as label) is **not allowed** — server rejects. Reason: label block content schema is incompatible with others (see [Block types](/tt-blocks/concepts/widget-types)). To change type → **rebuild a new block**. ## Will modifying the original sync to duplicates? **No.** Duplicate and original are two independent configs; modifying one doesn't affect the other. To unified-update multiple duplicates, edit each. ## Bulk duplication Currently the ⋯ menu is a single-block operation; **bulk duplication is not supported**. To quickly build multiple variants: - Duplicate one → modify fields → duplicate again → modify fields - During duplication, placement / visibility is preserved, can serve as a template for further derivation --- # Apply theme colors to blocks URL: https://docs.tantou.ai/tt-blocks/how-to/import-theme-colors/ Description: Use your published theme's colors as a color scheme on your blocks. Last updated: 2026-05-08T02:18:03.000Z Make blocks visually consistent with your storefront: the app can read your published theme's colors and offer them as an extra color scheme inside the [Advanced tab](/tt-blocks/editor/design). Tip: **"Theme palette derivation needs an OS 2.0 theme."** ## Steps ### 1. Open the Advanced tab Open the block editor → [Advanced tab](/tt-blocks/editor/design) → **"Color scheme"** card. ### 2. Find "From your theme" In the color scheme picker, scroll to the **"From your theme"** group. Theme-derived schemes are named **"Theme {n}"** or **"{themeName} Theme {n}"**. !["From your theme" section with multiple theme-derived scheme cards](https://static.tantou.ai/images/tt-blocks/2026/05/0fcb19a796d92ef8.png) ### 3. Apply Click a scheme card to apply it to the current block. ### 4. When derivation fails If the **"From your theme"** group is missing, your theme is not supported. Common reasons: | Reason | What to do | |:--|:--| | Theme is Vintage (e.g. Brooklyn) | Pick one of the 4 built-in schemes from the [Advanced tab](/tt-blocks/editor/design) | | Theme doesn't expose enough color settings | Use a built-in scheme, or contact the theme author | Empty state: **"No theme palette detected — pick a curated scheme below."** ![derivation-failed empty state](https://static.tantou.ai/images/tt-blocks/2026/05/0fcb19a796d92ef8.png) ## What happens when you switch themes? **Existing blocks are unaffected.** Each block keeps the colors and icon style it had at creation time — switching the storefront theme does not retroactively restyle published blocks. After switching, when you reopen a block: - The Advanced tab will show schemes derived from the new theme - Applying one is an explicit choice — nothing changes automatically - Typography follows the new theme; shape stays as-is ## Built-in schemes vs theme-derived | Source | When to pick | |:--|:--| | 4 built-in schemes (Plain Color / Plain Mono / Brand on White / Brand Fill) | You want a pre-designed look, or your theme isn't supported | | Theme-derived | You want blocks to fuse with the storefront theme's existing palette | Different blocks can use different schemes; one block uses one scheme at a time. ## Brand color exception Some components (brand icons like Amazon orange, Instagram pink) have built-in brand colors. Color scheme changes **do not override** brand-color fields — those are part of brand recognition. If you want brand icons to follow the scheme color instead, switch the brand icon's variant to **Mono**. --- # Schedule a campaign on / off URL: https://docs.tantou.ai/tt-blocks/how-to/schedule-campaign/ Description: Use the Schedule dimension to auto-launch and auto-end blocks for holiday or limited-time promotions. Last updated: 2026-05-08T02:02:35.000Z Use the [Target tab](/tt-blocks/editor/display)'s **Schedule** dimension to limit blocks to specific time windows — no need to manually monitor on / off. ## Steps ### 1. Enter Target tab → Schedule ![left SubNav with Schedule selected](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) ### 2. Set start time - **Now** — visible immediately when published - **Specific time** — pick date + 12-hour time (hour / minute / AM/PM) ### 3. Set end time - **Never** — until manually unpublished - **Specific time** — pick date + 12-hour time ### 4. Mind the timezone hint Bottom shows current timezone. ![Schedule dimension config (start + end + timezone hint)](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) ### 5. Verify Return to [Block list](/tt-blocks/dashboard) and check status badge: before start time displays **Scheduled**, after end displays **Expired**. ![dashboard Scheduled / Expired status badges side by side](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) --- # Translate block text for multi-language stores URL: https://docs.tantou.ai/tt-blocks/how-to/translate-widget/ Description: Languages tab actual workflow. Last updated: 2026-05-08T02:02:35.000Z Use the [Languages tab](/tt-blocks/editor/localization) to provide translations for the block's translatable fields per language. Storefront auto-switches based on buyer language. Untranslated fields auto-fall-back to default language (**"If a language has no value, it falls back to the default language."**). ## Steps ### 1. Confirm the shop has multi-language enabled Shopify Admin Settings → Markets / Languages → add target languages. ![Shopify Markets / Languages config page](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) ### 2. Enter the block's Languages tab [Languages tab](/tt-blocks/editor/localization). ### 3. Add a language Click **"Add language"** to open the available language picker; pick a target language. !["Add language" popup menu + new pill at top after selection](https://static.tantou.ai/images/tt-blocks/2026/05/0fcb19a796d92ef8.png) ### 4. Fill translations field by field In the per-component grouped table, the **"Default"** column is read-only (shop's primary language); each language has its own column. For the list of translatable fields by component type, see [Languages tab — Translation table](/tt-blocks/editor/localization). ![translation table (with at least one set, cross-language columns)](https://static.tantou.ai/images/tt-blocks/2026/05/0fcb19a796d92ef8.png) ### 5. Empty fields auto-fall-back Untranslated fields use the **"Default"** column value. ### 6. Delete a language Click × on the language pill; confirmation modal **"All {language} translations on this block will be deleted; untranslated fields fall back to default."** ![delete language confirmation modal](https://static.tantou.ai/images/tt-blocks/2026/05/0fcb19a796d92ef8.png) --- # Show different blocks by traffic source (UTM) URL: https://docs.tantou.ai/tt-blocks/how-to/utm-targeting/ Description: Show different blocks to TikTok / Email / Google visitors (Pro feature). Last updated: 2026-05-08T02:02:35.000Z Use [Target tab](/tt-blocks/editor/display)'s **UTM** dimension (**Pro** feature) to switch display by traffic source. Common scenarios: - TikTok visitors see exclusive coupons - Email visitors see returning-customer thank-you block - Google Ads visitors see product differentiation / trust badges ## Steps ### 1. Create multiple blocks Create one block per traffic source (use [Reuse block](/tt-blocks/how-to/duplicate-widget) to speed setup). ### 2. Configure UTM dimension for each Enter [Target tab](/tt-blocks/editor/display) → **UTM** → set **Include** / **Exclude**. | UTM row | Purpose | |:--|:--| | `utm_source` | Traffic source (tiktok / google / facebook / email, etc.) | | `utm_medium` | Medium (cpc / social / email / referral, etc.) | | `utm_campaign` | Campaign name (blackfriday / launch / valentines, etc.) | | `utm_term` | Keywords (search ads) | | `utm_content` | Creative ID (distinguish different assets in same campaign) | Custom UTM rows (e.g. `utm_id`, non-standard) can be added. ![UTM dimension config (5 standard rows + custom rows)](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) ### 3. Use corresponding utm params in placement channels In ad / email links, attach utm params: ``` https://shop.com/products/foo?utm_source=tiktok&utm_campaign=blackfriday ``` ### 4. Verify with Simulator In **Target tab**'s right **Simulator** sidebar, paste a real link with utm in the **URL** field. Tip: **"Paste a real URL: page type, selected variant (?variant=N), and UTM params (utm_source / medium / campaign / …) are parsed automatically. Product pages also fetch live metafields and variants."** ![Simulator sidebar URL field filled, real-time match feedback](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) ## UTM session persistence (important) Real visitors rarely keep UTM params across page navigations. The system records UTM on the **landing page** (the first page with UTM) into `sessionStorage`, and subsequent pages fall back to it (commit `599c1ec`): ``` 1. Customer enters from TikTok link → URL has utm_source=tiktok ↓ widget.js writes sessionStorage["__TTB_UTM__"] = { utm_source: "tiktok", ... } 2. Customer clicks other links in the store (e.g. product detail page) ↓ URL no longer has UTM ↓ evaluator falls back to sessionStorage 3. UTM dimension still matches utm_source = tiktok rule 4. Customer closes tab → session ends → UTM history cleared ``` This means merchants don't worry about "customer lost UTM after one ad click and second page view" — **session-wide persistent**. ## UTM matching rules | Case | Behavior | |:--|:--| | Multiple values in same UTM row | OR — any match wins (e.g. `utm_source` includes `tiktok` OR `instagram`, either source matches) | | Different UTM rows | AND — all must match (e.g. `utm_source = tiktok` AND `utm_medium = social`) | | **Include** vs **Exclude** | Within a row, exclude precedes include (first check exclude list, then include) | | UTM dimension not configured | Inactive — block visible to all traffic sources | ## UTM combination with other dimensions UTM dimension AND-combines with other 8 dimensions. For example: - UTM = `tiktok` + Pages = `Product page` = block shows only for TikTok visitors on product pages --- # Legal URL: https://docs.tantou.ai/tt-blocks/legal/ Description: Legal documents for TT Badges & Product Labels. Last updated: 2026-05-08T01:43:22.000Z Legal documents related to TT Badges & Product Labels. For convenience, this index lists all four; the canonical URLs below can be linked from the Shopify Partner Dashboard, app listing, or admin UI footer. ## Documents | Document | Purpose | |---|---| | [Privacy Policy](/tt-blocks/legal/privacy) | What data we collect, how we use it, where it's stored, your rights | | [Terms of Service](/tt-blocks/legal/terms) | Terms governing your use of the App, including subscription, acceptable use, liability | | [Data Processing Agreement](/tt-blocks/legal/dpa) | GDPR-compliant DPA between merchant (Data Controller) and us (Data Processor) | | [Refund and Subscription Policy](/tt-blocks/legal/refund) | Plans, billing, refund eligibility, cancellation, plan changes | ## Effective dates | Document | Effective | Last updated | |---|---|---| | Privacy Policy | April 8, 2024 | April 7, 2026 | | Terms of Service | April 8, 2024 | April 7, 2026 | | Data Processing Agreement | April 8, 2024 | April 7, 2026 | | Refund and Subscription Policy | April 8, 2024 | April 7, 2026 | ## Contact For legal questions, data subject requests, or compliance inquiries: support@tantou.ai --- # Data Processing Agreement URL: https://docs.tantou.ai/tt-blocks/legal/dpa/ Description: GDPR-compliant DPA between merchant (Controller) and TT Badges & Product Labels (Processor). Last updated: 2026-05-08T02:02:27.000Z **Effective date:** April 8, 2024 **Last updated:** April 7, 2026 This Data Processing Agreement ("DPA") forms part of the [Terms of Service](/tt-blocks/legal/terms) between you ("Merchant", acting as the **Data Controller** under GDPR) and Tantou AI ("Processor"). It governs the processing of personal data by the Processor on behalf of the Controller in connection with the use of TT Badges & Product Labels ("the App"). ## 1. Definitions Terms used here have the meanings set out in the EU General Data Protection Regulation 2016/679 ("GDPR"), including "personal data", "processing", "controller", "processor", "sub-processor", and "data subject". ## 2. Subject and duration The Processor processes personal data on behalf of the Controller for the duration of the App installation, terminated upon Merchant uninstalling the App or written termination of the [Terms of Service](/tt-blocks/legal/terms). ## 3. Nature and purpose of processing | Aspect | Detail | |---|---| | Nature | Storing block configuration; serving block rendering; aggregating non-identifiable analytics | | Purpose | Operating the App as described in the [Privacy Policy](/tt-blocks/legal/privacy) | | Processing operations | Collection, storage, retrieval, transmission, aggregation, and deletion | | Duration | For the lifetime of the App installation; data is deleted within 30 days of uninstall (see §12) | | Categories of personal data | See §4 | ## 4. Categories of data subjects and personal data | Data subject | Personal data | |---|---| | Merchant staff (admin users) | Shopify shop domain, OAuth session token (Shopify-issued, not user PII) | | Storefront visitors | Read at runtime in the visitor's browser only — see [Privacy Policy §2.2](/tt-blocks/legal/privacy) | The App does not store storefront-visitor PII server-side under normal operation. ## 5. Processor obligations The Processor shall: - Process personal data only on documented instructions from the Controller, including via the App's UI - Ensure persons authorized to process personal data are bound by confidentiality obligations - Implement appropriate technical and organizational security measures (see §9) - Assist the Controller in fulfilling data subject rights requests (Articles 15–22 GDPR), including via Shopify's mandatory privacy webhooks - Notify the Controller of any personal data breach without undue delay (see §11) ## 6. Sub-processors The Controller authorizes the Processor to engage the following sub-processors: | Sub-processor | Purpose | Region | |---|---|---| | Shopify Inc. | App authentication, metafield storage, billing | Global | | Cloudflare, Inc. | Compute, storage, and analytics infrastructure | Global edge | The Processor will notify the Controller before adding or replacing sub-processors. The Controller may object on reasonable grounds. ## 7. International transfers Personal data may be transferred outside the EEA where sub-processors operate. Such transfers rely on the following safeguards: | Sub-processor | Region | Transfer safeguard | |---|---|---| | Shopify Inc. | Global (primary: Canada, US) | EU Standard Contractual Clauses (SCCs); EU–U.S. Data Privacy Framework (where applicable); see [Shopify's DPA](https://www.shopify.com/legal/dpa) | | Cloudflare, Inc. | Global edge network | EU Standard Contractual Clauses (SCCs); EU–U.S. Data Privacy Framework (where applicable); see [Cloudflare's DPA](https://www.cloudflare.com/cloudflare-customer-dpa/) | ## 8. Data subject rights The Processor will assist the Controller in responding to data subject access, rectification, erasure, restriction, portability, and objection requests, primarily via Shopify's `customers/data_request` and `customers/redact` webhooks (see [Privacy Policy §7](/tt-blocks/legal/privacy)). ## 9. Security measures The Processor maintains the following measures: - TLS in transit - Encryption at rest via Cloudflare's storage layer - Access control to production infrastructure (least privilege) - Periodic security review ## 10. Audit rights The Controller may exercise audit rights in the following ways: - **Annual security summary** — request, no more than once per year, a summary of the Processor's security and data handling practices - **Written questionnaire** — submit a reasonable written questionnaire about specific processing activities; the Processor will respond within 30 days - **Third-party audit reports** — rely on publicly available audit reports of sub-processors (e.g., Shopify's SOC 2; Cloudflare's ISO 27001, SOC 2) Detailed on-site audits are not provided. The Controller bears any reasonable third-party costs incurred for additional audits beyond the above. ## 11. Data breach notification The Processor will notify the Controller of any personal data breach affecting Controller data without undue delay, and in any event within 72 hours of becoming aware. The notification will include the nature of the breach, categories and approximate number of data subjects and records affected, likely consequences, and the measures taken or proposed to address the breach. ## 12. Return or deletion of data Upon termination of the App installation: - Personal data is deleted within 30 days (in line with Shopify's `shop/redact` requirement), except where retention is required by law - The Controller may export block configuration before uninstalling the App ## 13. Liability Liability under this DPA is governed by the [Terms of Service](/tt-blocks/legal/terms) §9. ## 14. Contact For DPA matters and data subject requests: support@tantou.ai. --- # Privacy Policy URL: https://docs.tantou.ai/tt-blocks/legal/privacy/ Description: How TT Badges & Product Labels collects, uses, and protects information. Last updated: 2026-05-08T02:02:27.000Z **Effective date:** April 8, 2024 **Last updated:** April 7, 2026 ## 1. About this app TT Badges & Product Labels ("we", "us", "the App") is a Shopify app that lets merchants compose visual blocks (badges, buttons, coupons, payment icons, brand icons, text, label chips) and render them on the storefront via a theme app extension. The App is operated by Tantou AI. This Privacy Policy describes what data we receive when the App is installed, how we use it, where it is stored, and your rights regarding that data. ## 2. Information we receive ### 2.1 From Shopify (merchant store) When the App is installed on a Shopify store, we receive the following data through authenticated Shopify APIs: - **Store-enabled languages** — to support multi-language block content - **Read-only theme files** — to derive style data and identify where blocks render in the theme - **Product, collection, and variant metadata** — read for visibility rules; we also write block configuration back to product metafields - **Product inventory levels** — for inventory-based visibility rules - **Public product and inventory data** — for block rendering on collection pages We do **not** request access to customer personal data, orders, or payment information. ### 2.2 From storefront visitors When a block renders on a storefront page, the App's storefront script evaluates visibility rules in the visitor's browser. Depending on what the merchant configures, this may involve reading from page context: - Page URL and UTM parameters - Customer login state (logged in / logged out) - Customer tags, total spent, order count (only if the merchant configures customer-targeted visibility rules) - Country, device type, browser language This information is **read from the visitor's browser context only** and is not transmitted to our servers, except in aggregated, non-identifiable form for analytics (see Section 4). ## 3. How we use information We process personal data on the following legal bases under GDPR Article 6: - **Performance of a contract** (Art. 6(1)(b)) — to provide and operate the App as agreed in the [Terms of Service](/tt-blocks/legal/terms) - **Legitimate interests** (Art. 6(1)(f)) — to maintain service quality, debug errors, and aggregate non-identifiable performance metrics - **Compliance with legal obligations** (Art. 6(1)(c)) — to respond to Shopify's mandatory privacy webhooks (see Section 7) We use the data we receive to: - **Operate the editor and renderer** — store and serve block configuration, evaluate visibility rules - **Service operations** — aggregate, non-identifiable performance metrics (impression count, click count, error counts) - **Compliance** — respond to Shopify's mandatory privacy webhooks (see Section 7) We do **not**: - Sell, rent, or share merchant or visitor data with advertisers or data brokers - Build cross-shop visitor profiles - Use the data for any purpose outside the App's stated function ## 4. Where data is stored Block configuration, authentication sessions, and aggregated non-identifiable analytics events are stored on Cloudflare's secure cloud infrastructure. A copy of the block configuration is mirrored to Shopify metafields, which are owned by the merchant store. **Security measures** — Data in transit is protected by TLS. Data at rest is encrypted by the underlying provider. Access to production infrastructure follows the principle of least privilege, and we conduct periodic security reviews. **International transfers** — Data may be transferred and processed outside the European Economic Area (EEA) where Shopify and Cloudflare operate. Such transfers rely on the safeguards each provider maintains, including Standard Contractual Clauses (SCCs) and the EU–U.S. Data Privacy Framework where applicable. ## 5. Third parties - **Shopify** — required for App operation; subject to [Shopify's Privacy Policy](https://www.shopify.com/legal/privacy) - **Cloudflare** — infrastructure provider (compute, storage, CDN) We do not share data with any other third parties. ## 6. Data retention | Event | Behavior | |---|---| | Active installation | Block configuration retained for the lifetime of the App installation | | Merchant uninstalls App | When Shopify notifies us of the uninstall, merchant data is deleted within 30 days (in line with Shopify's `shop/redact` requirement) | | Customer data request | See Section 7 | ## 7. Your privacy rights ### 7.1 GDPR data subject rights If you are a resident of the European Economic Area (EEA), you have the following rights under GDPR Articles 15–22: - **Right of access** — confirm whether we hold your personal data and obtain a copy - **Right to rectification** — correct inaccurate data - **Right to erasure** ("right to be forgotten") — request deletion - **Right to restriction** — limit how we process your data - **Right to data portability** — receive your data in a structured, machine-readable format - **Right to object** — object to processing based on legitimate interests - **Right not to be subject to automated decision-making** — see Section 7.3 - **Right to lodge a complaint** — file a complaint with your local supervisory authority In compliance with Shopify's mandatory privacy webhooks, the App responds to: | Shopify webhook | Our response | |---|---| | `customers/data_request` | Provide an export of any data we hold about the customer. Typically none — we do not store customer PII. | | `customers/redact` | Delete any data we hold about the customer. Typically none. | | `shop/redact` | Delete all data associated with the merchant's shop. | Storefront visitors should contact the merchant first; the merchant routes the request to Shopify, which triggers the webhook to us. Merchants can also reach us directly at support@tantou.ai. ### 7.2 California residents (CCPA / CPRA) If you are a California resident, you have rights under the California Consumer Privacy Act (CCPA) as amended by CPRA, including: - The right to know what personal information we collect, use, and disclose - The right to delete personal information we have collected - The right to correct inaccurate personal information - The right to opt out of the "sale" or "sharing" of personal information — **we do not sell or share personal information** - The right to non-discrimination for exercising your rights To exercise these rights, contact support@tantou.ai. ### 7.3 Automated decision-making We do **not** make decisions based solely on automated processing, including profiling, that produce legal effects or similarly significantly affect you. ## 8. Cookies and tracking - **Admin UI** (embedded in Shopify Admin) — relies on Shopify's own session cookies for authentication; these are set by Shopify, not by us. We do not set our own cookies in the admin and do not use third-party tracking cookies. - **Storefront script** — does not set cookies and does not use fingerprinting techniques. ## 9. Children's privacy The App is not directed to children under 13 (or under 16 in the European Union, depending on member state law). We do not knowingly collect data from children. ## 10. Changes to this policy We may update this Privacy Policy from time to time. The "Last updated" date above reflects the latest revision. Material changes will be communicated to merchants at least 30 days in advance via the App interface or email; non-material updates take effect upon posting. ## 11. Contact For privacy questions, data subject requests, or complaints, contact: - Email: support@tantou.ai --- # Refund and Subscription Policy URL: https://docs.tantou.ai/tt-blocks/legal/refund/ Description: Subscription, billing, refund, and cancellation terms for TT Badges & Product Labels. Last updated: 2026-05-08T02:02:27.000Z **Effective date:** April 8, 2024 **Last updated:** April 7, 2026 ## 1. Plans | Plan | Price | Features | |---|---|---| | Free | $0 | Visual editor, theme-aware color schemes, basic visibility rules (page / device / login state); see [Plans](/tt-blocks/plans) | | Pro | $9.90 USD/month or $99 USD/year | All features (see [Plans](/tt-blocks/plans)) | ## 2. Billing - Pro is billed through Shopify's app billing API; charges appear on your Shopify invoice - The billing cycle is monthly or annual depending on the plan you select; charges begin after any applicable free trial ends - Pricing is in USD unless otherwise stated; Shopify converts to your shop currency - All charges are exclusive of any applicable taxes ## 3. Free trial Pro includes a **7-day free trial**. The trial begins when you upgrade to Pro. You may cancel at any time before the trial ends without being charged; if not cancelled, billing begins automatically when the trial period ends. ## 4. Refund eligibility We generally do not provide refunds for Pro subscription charges, except in the following cases: - **Service unavailable** — sustained service outage attributable to the App (not Shopify or theme issues) - **Inadvertent upgrade** — accidental upgrade where Pro features were not used; request within 7 days - **Required by applicable law** — local consumer protection regulations Refund decisions are at our discretion and made in good faith. ## 5. How to request a refund Email support@tantou.ai with: - Your Shopify shop domain - The Shopify invoice number - A brief description of the reason We will respond within 5 business days. ## 6. Cancellation - You may cancel Pro at any time by downgrading to Free in the App's [Settings](/tt-blocks/settings) or by uninstalling the App - Pro features remain available until the end of the current billing cycle; no proration is provided - After cancellation, Pro-only fields in your block configuration are stripped per the [plan policy](/tt-blocks/plans) ## 7. Plan changes - **Upgrade** (Free → Pro): takes effect immediately; charged from the upgrade date - **Downgrade** (Pro → Free): takes effect at the end of the current billing cycle ## 8. Failed payments If a Shopify-issued charge fails: - Shopify will retry per its standard schedule - After repeated failures, your subscription will be downgraded to Free - You may resume Pro by re-subscribing through the App ## 9. Changes to pricing We may change pricing or plan structure with at least 30 days' notice. Existing subscribers will be notified via the App or email. ## 10. Contact For billing questions: support@tantou.ai --- # Terms of Service URL: https://docs.tantou.ai/tt-blocks/legal/terms/ Description: Terms governing merchant use of TT Badges & Product Labels. Last updated: 2026-05-08T02:02:27.000Z **Effective date:** April 8, 2024 **Last updated:** April 7, 2026 ## 1. Acceptance of terms By installing or using TT Badges & Product Labels ("the App"), you ("Merchant") agree to these Terms of Service. The App is operated by Tantou AI ("we", "us"). If you do not agree, do not install or use the App. ## 2. Eligibility You must operate a Shopify store in good standing and have authority to bind that store / business under these terms. ## 3. The App TT Badges & Product Labels lets merchants compose visual blocks (badges, buttons, coupons, payment icons, brand icons, text, label chips) and render them on the storefront via a theme app extension. The App is provided as Software-as-a-Service. ## 4. Subscription and billing | Plan | Price | Billing | |---|---|---| | Free | $0 | n/a | | Pro | $9.90 USD/month or $99 USD/year | Through Shopify's app billing | Cancel anytime via Shopify Admin. See [Refund Policy](/tt-blocks/legal/refund) for refund terms. ## 5. Acceptable use You may not use the App to: - Display content that is illegal, infringing, deceptive, harassing, or violates Shopify's Acceptable Use Policy - Interfere with or disrupt the App's functionality - Attempt to reverse-engineer, decompile, or extract source code (other than as permitted by law) - Resell or redistribute the App or its outputs without our written permission ## 6. Merchant content and data You retain ownership of all content and data you submit (block configuration, copy, product references). You grant us a limited, non-exclusive license to process this content solely to provide the App. See [Privacy Policy](/tt-blocks/legal/privacy) for data handling. ## 7. Intellectual property The App, including its source code, design, branding, and documentation, is owned by us or our licensors. These terms grant you no rights to our trademarks. Feedback you provide may be used by us without restriction. ## 8. Service availability The App is provided "as is" and "as available", without warranties of any kind. We do not guarantee uninterrupted operation; planned maintenance and upstream (Shopify / Cloudflare / theme) issues may interrupt the service. We may update, modify, or discontinue features at any time. ## 9. Limitation of liability To the maximum extent permitted by law, our total liability arising from or related to your use of the App is limited to the amount you paid for the App in the 12 months preceding the claim. We are not liable for indirect, incidental, consequential, or punitive damages, including loss of profits, revenue, or data. ## 10. Termination - You may uninstall the App at any time through your Shopify admin; cancellation takes effect at the end of the current billing cycle (see [Refund Policy §6](/tt-blocks/legal/refund)) - We may suspend or terminate your access with reasonable notice if you breach these terms or use the App in a way that risks harm to merchants or end customers; in cases of severe breach (illegal use, security threats), we may terminate immediately without prior notice - Annual subscriptions cancelled before the renewal date remain active until the paid period ends; we do not provide prorated refunds for unused days (see [Refund Policy §4](/tt-blocks/legal/refund)) - Upon termination, your block configuration is deleted per [Privacy Policy §6](/tt-blocks/legal/privacy) ## 11. Changes to these terms We may update these terms from time to time. Material changes will be communicated to merchants at least 30 days in advance via the App or email; non-material updates take effect upon posting. Continued use after the changes constitutes acceptance. ## 12. Contact For questions about these terms: support@tantou.ai. --- # Plans and pricing URL: https://docs.tantou.ai/tt-blocks/plans/ Description: What you get on Free vs Pro, demo quotas, and how upgrades and downgrades work. Last updated: 2026-05-08T02:02:35.000Z TT Badges & Product Labels offers two plans: **Free** and **Pro** (no enterprise tier). For current pricing, see the [Shopify App Store page](https://apps.shopify.com/tt-trust-badges-and-icons). Upgrade entry: [Settings](/tt-blocks/settings) → Plan & billing → **"Manage plan on Shopify"** → jumps to Shopify billing. ## What each plan includes | Capability | Free | Pro | |:--|:--|:--| | Unlimited blocks · 11 component types · 7 placements · 4 color schemes | ✅ | ✅ | | Theme-derived color schemes · multi-language translation | ✅ | ✅ | | Stats retention (last 30 days) | ✅ | ✅ | | Email support | ✅ | ✅ | | Visibility rules — on/off for **Pages**, **Products**, **Variants**, **Customers**, **Geo**, **Device**, **Schedule**, **Traffic source** | ✅ | ✅ | | **Login state** (logged-in / guest) under Customers | ✅ | ✅ | | Device type (Mobile / Desktop) | ✅ | ✅ | | **Specific products** — pick particular products | up to 5 | unlimited | | Advanced filters under **Products** / **Variants** / **Customers** | ❌ | ✅ | | **Country** (Geo), **Schedule** (start / end / recurring), **Traffic source** (UTM / referrer) | ❌ | ✅ | | **Hide theme elements** + per-block **Advanced CSS** | ❌ | ✅ | ## Free demo quotas Two visibility fields offer a "try-before-buy" demo on Free so you can see how they work before upgrading: - **Specific products** — pick up to 5 specific products. The 6th picks up an upgrade prompt: **"Free quota used up (5 max). Upgrade to Pro for unlimited."** - **Login state** — toggle between guests and logged-in customers (no count quota). Other Pro-only fields are entirely gated — they show with a lock icon and a Pro upgrade prompt. ## Save then upgrade You can configure Pro fields while on Free; the editor doesn't stop you. On save: - If the configuration fits within demo quotas → it saves normally and Pro fields are kept - If it doesn't fit → the editor shows an upgrade prompt: - **Upgrade** → opens Shopify billing → after upgrading, the block runs with full Pro fields - **Skip** → the block is saved at Free quota and excess fields are removed ## Switching plans | Switch | What happens | |:--|:--| | Free → Pro | Takes effect immediately. Pro fields you'd previously hit a quota on can come back. | | Pro → Free | Downgrade lands at the end of the current billing cycle. Pro-only fields stop applying on the storefront and are removed on the next save. | ## Refunds See [Refund and Subscription Policy](/tt-blocks/legal/refund). --- # Reference URL: https://docs.tantou.ai/tt-blocks/reference/ Description: Fill kinds, icon library, animations, anchors, font weights, and more. Last updated: 2026-05-08T02:02:41.000Z Reference tables for all enums and options — look up as needed. ## Fill kinds From i18n `fill.kind.*`: - **Solid** (`solid`) - **Gradient** (`gradient`) — **Color 1** + **Color 2** + **Angle** - **Tricolor** (`tricolor`) — **Color 1** + **Color 2** + **Color 3** + **Angle** - **Pattern** (`pattern`) — **"Pattern is provided by the color scheme. Switch fill type to solid or gradient to customize."** ![4 fill type preview thumbnails](https://static.tantou.ai/images/tt-blocks/2026/05/01c5d60c335b3399.png) ## Icon library [Badge](/tt-blocks/components/badge) / [Button list](/tt-blocks/components/button-list) / [Coupon](/tt-blocks/components/coupon) icon picker has 5 tabs: - **Icons** — generic icon library (Phosphor) - **Brand** — filtered by category: **E-commerce** / **Social media** / **SNS**; variants: **Color** / **Mono** - **Payment** — payment methods (Visa / Mastercard / Amex etc.) - **Shapes** — badge shape selector - **URL** — custom URL or emoji (placeholder **"URL or emoji"**) Icon weights (some icons): - **Regular** / **Thin** / **Filled** / **Duotone** ![icon picker 5 tabs, 1 screenshot each](https://static.tantou.ai/images/tt-blocks/2026/05/01c5d60c335b3399.png) ## Font weights From i18n `opt.*`: - **Regular** / **Medium** / **Semibold** / **Bold** / **Extra bold** / **Black** / **Off** ## Border styles - **Solid** / **Dashed** / **Dotted** ## Alignment - Main axis: **Start** / **Center** / **End** / **Space between** / **Space around** - Cross axis: **Left** / **Center** / **Right** / **Stretch** - Container width: **Fill** / **Auto** ## Animation | Type | Trigger | Applicable components | |:--|:--|:--| | Hover animation | Mouse hover | All component types | | Button animation (nudge) | Sustained attention | Button / Coupon / Button list children | | Display animation | Block enters viewport | Block container | | Slide entrance | Label block enters | label_chip | `prefers-reduced-motion` system setting → all animations auto-degrade. ## Mount anchors Merchant-selectable 7 cards correspond to 9 + 1 data-layer anchor values. Main anchor keys: | Anchor | Type | Merchant card | |:--|:--|:--| | `auto_product` | complex | Product page | | `auto_cart` / `auto_cart_drawer` | complex | Cart Page / Cart Drawer | | `auto_above_footer` / `auto_below_footer` | complex | Footer | | `auto_footer` | complex (legacy) | — | | `float_top` / `float_bottom` / `float_left` / `float_right` | **floating** | Floating Icons | | `label` | label | Product image overlay | Full internal anchor list + cascade + 65-theme selector matrix + theme override + customAnchorSelectors: see [Anchors and cascade table](/tt-blocks/reference/anchors-cascade). ## Placement modes `placement.mode`: - `auto` — system picks specific DOM position based on theme - `manual` — merchant places via manual block in theme editor See [Placement modes](/tt-blocks/reference/placement-modes). ## Status badges From i18n `status.*`: - **Published** / **Unpublished** / **Pending** / **Error** / **Custom** / **Scheduled** / **Expired** / **Hidden** ## Drag / keyboard interactions - **List view row drag** — mouse-hold the row's left handle to drag; touch screen long-press then drag - **Editor component drag** — Content tab component list row handles - **Shortcuts**: - **Cmd / Ctrl + Z** — undo - **Cmd / Ctrl + Shift + Z** — redo - **Cmd / Ctrl + S** — save (some pages support) - **Esc** — close dialog / cancel edit - Keyboard accessibility: all interactive elements support Tab navigation + Enter trigger ## Browser support | Browser | Min version | |:--|:--| | Chrome | 88+ | | Safari | 14+ | | Firefox | 85+ | | iOS Safari | 14+ | | Android Chrome | 88+ | ## Data retention / limits | Item | Behavior | |:--|:--| | Single block config size | 96 KiB hard limit | | customAnchorSelectors | ≤ 24 per block | | Block creation count | Unlimited (Free / Pro) | | Shopify checkout block | ≤ 1 per shop (Shopify platform limit) | | Stats retention | Last 30 days | | Deleted block | Immediate deletion (unrecoverable) | | Uninstall app cleanup | Via `app/uninstalled` webhook (see [Privacy Policy](/tt-blocks/legal/privacy)) | --- # Placement reference and custom anchors URL: https://docs.tantou.ai/tt-blocks/reference/anchors-cascade/ Description: The 7 placement cards in the editor, plus custom CSS selectors when your theme isn't auto-detected. Last updated: 2026-05-08T02:42:45.000Z This page is a quick reference for the 7 placement options shown in the editor and how to fill **custom anchor selectors** when your theme isn't auto-detected. ## The 7 placement cards The Target tab's Placement section offers seven cards: | Card | What it does | |:--|:--| | **Product page** | Mounts near the product page's Add-to-cart button (the system picks the exact spot for your theme) | | **Footer** | Two buttons inside the card — choose **Above footer** or **Below footer** | | **Floating Icons** | Pinned to a viewport edge — choose **Top**, **Bottom**, **Left**, or **Right** | | **Cart Drawer** | Mounts inside the cart drawer | | **Cart Page** | Mounts on the cart page | | **Custom Position** | You drop the block onto a theme template manually (see [Custom placement](/tt-blocks/how-to/custom-placement)) | | **Product image overlay** | Overlay on product images (Label block; PDP and collection cards) | ## Custom anchor selectors (when auto-detection misses your theme) If your theme isn't recognized, the diagnostic panel shows **"No available placement on this page"**. Fill custom CSS selectors in the [Target tab](/tt-blocks/editor/display) advanced section to tell the app where to mount. Example: ```json { "product": ["#alt-buy-button-region"], "productList": [], "productMedia": [], "exclude": [".competitor-badge"] } ``` | Field | What it controls | |:--|:--| | `product` | Where the block mounts on a product page (highest priority — overrides the auto-detected location) | | `productList` | Each product card on collection / search / recommendation pages | | `productMedia` | The image / media slot inside a product card (used for image overlays) | | `exclude` | Selectors to skip — e.g. a competitor's badge or a theme element you don't want the block near | **Limits**: - Up to 24 selectors per block - Use real CSS selectors (`.class`, `#id`, `[data-attr]`, etc.) — anything jQuery-only or invalid is ignored **Tip**: open your storefront, right-click the spot you want the block at → **Inspect** → copy a stable selector (prefer a class or `data-` attribute over generated IDs). ## Diagnostics: which spot did it actually use? The diagnostic panel in the [Target tab](/tt-blocks/editor/display) StickyBar shows the **actual mount target** picked at runtime. Useful when the block appears, but not where you expected. ![diagnostic panel showing actual mount target](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) ## Related - Auto vs manual placement modes: [Placement modes](/tt-blocks/reference/placement-modes) - Manual placement walkthrough: [Custom placement](/tt-blocks/how-to/custom-placement) --- # Placement modes — auto vs manual URL: https://docs.tantou.ai/tt-blocks/reference/placement-modes/ Description: Two ways to place a block on your storefront and when to choose each. Last updated: 2026-05-08T02:43:33.000Z There are two basic ways to place a block: | Mode | What it does | How you pick it | |:--|:--|:--| | **Auto** | The app picks the spot for you, based on your theme's structure | Pick one of the location cards (full list: [Placement reference](/tt-blocks/reference/anchors-cascade)) | | **Manual** | You drop the block onto a specific theme template yourself | Pick the **Custom Position** card | ## When to choose Auto - You want it to just work, without touching theme code - The target spot is a standard Shopify location (near Add-to-cart, cart, footer, etc.) - Your theme is in the supported list (most cases) In Auto mode: - Pick any of the location cards (see [Placement reference](/tt-blocks/reference/anchors-cascade)) - The app finds the right spot for your theme automatically - If the theme isn't supported, the diagnostic panel shows **"No available placement on this page"** — switch theme, switch placement, or fill [custom anchor selectors](/tt-blocks/reference/anchors-cascade) ## When to choose Manual - You want exact control (e.g. mount inside a specific custom section) - Your theme isn't supported and custom anchors aren't flexible enough - You want to drop the same block at different spots across multiple templates In Manual mode: - Pick **Custom Position** → the editor shows the block ID and an **"Add to theme"** button - Open the Shopify theme editor → drop the **TT Badges & Product Labels** block onto the section you want → paste the block ID into the block's settings - Save the theme; the block renders at that position Full walkthrough: [Custom placement](/tt-blocks/how-to/custom-placement). ## Switching between modes Switching placement cards keeps everything else (visibility rules, components, color scheme) intact — only the placement itself changes. The editor's save bar appears so you can save the new placement. ## Diagnostics In Auto mode, the [Target tab](/tt-blocks/editor/display) diagnostic panel shows the actual spot the block landed on — useful when the block appears but not where you expected. In Manual mode, the diagnostic panel just shows **"Custom Position"** (the block goes wherever you dropped it). ## Related - Custom anchor selectors and the placement reference: [Placement reference and custom anchors](/tt-blocks/reference/anchors-cascade) - Manual placement step-by-step: [Custom placement](/tt-blocks/how-to/custom-placement) --- # Settings URL: https://docs.tantou.ai/tt-blocks/settings/ Description: Admin UI language and subscription billing. Last updated: 2026-05-08T02:02:35.000Z Controls the TT Badges & Product Labels admin language and subscription. Access from the home page top-right **"Settings"**. ![Settings page overview](https://static.tantou.ai/images/tt-blocks/2026/05/9eda79e462c579b5.png) ## Top - Breadcrumb: **Blocks** / **Settings** - Primary action: **"Save"** button ## Admin UI language - Card title: **"Admin UI language"** - Description: **"Choose the language used in the block editor and settings screens."** - Field label: **"UI language"** — combobox listing 20 supported languages - Hint below: **"Auto-set to your Shopify account language on first visit."** ![Admin UI language card with dropdown expanded](https://static.tantou.ai/images/tt-blocks/2026/05/9eda79e462c579b5.png) ## Plan & billing - Card title: **"Plan & billing"** + plan badge (**Free** / **Pro**) - Status line: **"You're on the Free plan."** / **"You're on the Pro plan."** - **"Manage plan on Shopify"** button → opens the billing page in Shopify ![Plan & billing card comparing Pro and Free states](https://static.tantou.ai/images/tt-blocks/2026/05/6df01bfb1188719d.png) --- # Storefront behavior URL: https://docs.tantou.ai/tt-blocks/storefront/ Description: How blocks behave on the customer-facing storefront — responsive, coupon click, popover, multi-language, SEO, analytics. Last updated: 2026-05-08T02:39:47.000Z What customers see and do on the storefront when a block is published. Knowing this helps you choose the right placement and content for each block. ## Responsive - Same block adapts to desktop and mobile by switching field values (icon size / spacing / font size, etc.) — every visual field has a desktop value and a mobile value - Default breakpoint is 768 px (matches most Shopify themes; tunable in Advanced settings) - The editor's desktop / mobile preview matches what customers see on those viewports ![same block rendered on desktop vs mobile](https://static.tantou.ai/images/tt-blocks/2026/05/5082897940db1504.png) ## Coupon — click to copy and apply Hint: **"Copied to clipboard and applied to checkout."** When a customer clicks a coupon code: - The code is copied to the clipboard with a **"Copied!"** toast - The discount is auto-applied to the next checkout (only if the code exists in your Shopify Discounts) See [Make coupon work](/tt-blocks/how-to/coupon-setup). ## Badge popover - Trigger: **Click** or **Hover** (your choice in the editor) - Content: title + description + link (optional) - Close: click outside or press Esc ![popover trigger and close](https://static.tantou.ai/images/tt-blocks/2026/05/f27f4c7c4ef89849.png) ## Multi-language Blocks read the buyer's locale and show the translation you provided in the editor's Languages tab. If a translation is missing for that locale, the default-language text is shown instead. ## Performance - One shared script is cached on Cloudflare's CDN - Doesn't block the theme's first paint - Bundle is small enough not to be noticeable on real shopper devices ## Theme conflicts - Block fonts default to your theme's font (you can override per block in the editor) - z-index inherits from the mount point — no surprise stacking - Block CSS is namespaced so it doesn't leak into theme styles ## Accessibility - All interactive elements (buttons, coupon click, popover triggers) support keyboard navigation - aria-label / aria-describedby are added where needed - Color contrast is determined by the color scheme you pick — please self-check - Respects `prefers-reduced-motion` (animations auto-degrade for visitors with reduced-motion enabled) ## Browser support See [Reference — Browser support](/tt-blocks/reference) for the minimum versions. ## SEO - Block content is rendered client-side, which means **search engines do not reliably index it** - For text that should be indexed (key marketing copy, product details), keep it in the theme's native HTML, not in a block - Google partially executes JavaScript and may pick up some rendered output, but this is not guaranteed ## Analytics Each block sends three event types when it appears on the storefront: | Event | Trigger | |:--|:--| | `impression` | Block was rendered for a visitor | | `click` | Visitor clicked a button, badge, brand icon, coupon, or payment icon inside a block | | `error` | Block failed to mount or render | You can see aggregated impression and click data (last 30 days) in the [Block list](/tt-blocks/dashboard). ## Render consistency What you see in the editor preview is what ships to the storefront — they share the same rendering path. ## Label block (product image overlay) The Label block has extra behavior on collection pages: - It batch-fetches product data so the chips appear together, not one at a time - It deduplicates: multiple Label blocks won't overlay the same image twice - If the product card image is wrapped in a link, the chip uses a click handler so it doesn't break the card link See [Quick start (Product image overlay)](/tt-blocks/getting-started/quick-start-label). --- # Troubleshooting URL: https://docs.tantou.ai/tt-blocks/troubleshooting/ Description: Diagnose blocks that don't show on the storefront, plus limits and common errors. Last updated: 2026-05-08T02:23:42.000Z The fastest way to debug a block is the **"Runtime diagnostics"** + **Simulator** in the [Target tab](/tt-blocks/editor/display). This page covers reading them and a standard checklist for "block published but not showing on storefront". ## Diagnostic panel The diagnostic panel sits in the Target tab StickyBar and tells you exactly which rule is hiding the block. Subtitle: **"Based on Simulator preview, not actual storefront data."** ### What each verdict means | Verdict | Meaning | Fix direction | |:--|:--|:--| | **Visible** | All good | — | | **Page type mismatch: this block targets {expected} pages, visitor is on {got}.** | Block mount page ≠ visitor page | Check [Placement](/tt-blocks/editor/display) and [Pages](/tt-blocks/editor/display) settings, or adjust the Simulator URL | | **Blocked by display rule** | A visibility rule didn't match | Switch through the 8 visibility dimensions and check each in the Simulator | | **No available placement on this page** | The theme has no available anchor on this page | Switch theme, switch placement, or use [Custom Position](/tt-blocks/how-to/custom-placement) | | **Page rule no match** | The [Pages](/tt-blocks/editor/display) rule filtered this page out | Add the current page type to the **Include** list | | **Visitor login state doesn't match** | The [Customers](/tt-blocks/editor/display) rule filtered this visitor out | Adjust the **Login state** setting | | **Placement not set** | The [Placement](/tt-blocks/editor/display) field is missing | Pick a mount location | | **Invalid CSS selector** | The [Hide theme elements](/tt-blocks/editor/display) field (Pro) has a bad selector | Fix the CSS selector syntax | ![diagnostic modal (one screenshot per verdict)](https://static.tantou.ai/images/tt-blocks/2026/05/57cd379bc6a7f9b6.png) When more than one rule fails, the panel lists every failing rule at once so you can fix them in one pass instead of one-by-one. ## Simulator In the [Target tab](/tt-blocks/editor/display) right sidebar, fill in a virtual customer profile to see how rules react: - **URL** — auto-parses page type + UTM - **Device** / **Login state** / **Country** (segmented control) - **Customer tags** / **Total spent** / **Order count** (input) Switching the persona updates the verdict in real time without affecting what you save. ## Checklist: block is published but doesn't show on the storefront Run through these in order: ### 1. Is the app embed enabled? Go to [Block list](/tt-blocks/dashboard) → StatsRow → **"App status"** card: - **"Active"** — good - **"Inactive"** — click **"Activate"** to jump to the theme editor - ⚠️ **"Switching themes resets this toggle — re-enable after changing themes."** ### 2. Check the diagnostic panel Open the block editor → [Target tab](/tt-blocks/editor/display) → top StickyBar or diagnostic button → see which rule is failing and use the table above. ### 3. Verify with Simulator In the **Simulator** sidebar, paste a real link (with UTM params, etc.) and check the verdict. ### 4. Custom Position scenarios If you're using [Custom Position](/tt-blocks/how-to/custom-placement): - Confirm the Tantou block was added in the theme editor with the correct **block ID** pasted in - Confirm the theme is saved - Confirm the block is on a published template (not a draft) ### 5. Contact support Email with: - Block ID (use the **"Copy ID"** button on the block list card) - Storefront URL - Browser and OS - A screenshot of the storefront page where it's missing - What you expected vs what you see ## Common errors ### "Save failed" / "Block too large" The block exceeds the 96 KiB size cap. - Check for very long Custom CSS or many duplicated components - Split into multiple blocks — visibility rules can give you the same effect ### "Free quota used up" A field exceeds the demo quota for Free shops (products / variants etc.). - Reduce the number of items, or upgrade to Pro - See [Plans and pricing](/tt-blocks/plans) ### "Cross-type switch not allowed" A label-type block can't be changed to a non-label block, and vice versa (see [Block types](/tt-blocks/concepts/widget-types)). - To change type, create a new block. --- # Block creation wizard URL: https://docs.tantou.ai/tt-blocks/wizard/ Description: Three-step flow — placement, template, color scheme. Last updated: 2026-05-08T02:02:35.000Z Click **"Create block"** on the home page to enter the wizard. Three steps to complete, then enter the editor. ![Wizard first screen with top step indicator and Step 1 placement cards](https://static.tantou.ai/images/tt-blocks/2026/05/8f1ffe39a359c06b.png) ## Top navigation - Title: **"Create block"** - **"Cancel"** / **"Back"** buttons - Step indicator: **Placement** → **Template** → **Style**, current step highlighted ![Top three-step indicator closeup](https://static.tantou.ai/images/tt-blocks/2026/05/c08d0704ce3ad1a6.png) ## Step 1 — Placement 7 same-level cards, each = one mount location. Click the card's bottom **"Pick this position"** button to next step. | Card | Tip | |:--|:--| | **Product page** | Display below the "Add to cart" button on the product page. | | **Footer** | Display in the storefront footer. Two buttons within: **"Above footer"** / **"Below footer"**. | | **Floating** | Pin at viewport edge. 4 edges within: **"Top"** / **"Bottom"** / **"Left"** / **"Right"**. | | **Cart Drawer** | Display in the cart drawer. | | **Cart Page** | Display on the cart page. | | **Custom Position** | Embed at any theme location. | | **Product image overlay** | Pin a label to product images (PDP main image or collection card image). | Each card's right side shows position **"Preview"**. Tip: **"Specific DOM position is auto-selected by the system based on theme — merchant doesn't choose."** ![Step 1 placement card grid with single card detail showing SVG preview and Floating four-edge selector](https://static.tantou.ai/images/tt-blocks/2026/05/0e0605680a4a33d4.png) ## Step 2 — Template Subtitle: **"Pick a template"**. Lists all templates by category, with **"Matches this position"** at the top (recommended row, with **"Recommended"** badge). Template categories: - **Buttons** — marketplace / quick links / quick icons / discount - **Badges** — Trust ticker / Trust mono stack - **Social** — Social row / Social column / Messengers - **Payment** — Payment icons / Payment mono / Trust+payment combo - **Labels** — Sale / New arrivals / Low stock / Natural Each card has preview image, name, optional tip. Click **"Use this template"** to next step. ![Step 2 template gallery with recommended row and all categories](https://static.tantou.ai/images/tt-blocks/2026/05/7544d8eb95413887.png) ## Step 3 — Style Subtitle: **"Pick a color scheme"**. Tip: **"Schemes patch only colors — your template's layout, text, and icons stay as-is. You can change this later in the editor."** A 4-column **"Style"** picker with internal presets and (if theme supports) **"From your theme"** group. Built-in 4 presets: - **Plain Color** — "Light bg + dark text — third-party icons keep brand color." - **Plain Mono** — "Pure black & white chrome — third-party icons in mono." - **Brand on White** — "White-bg buttons + brand color icon and text. Each row uses the third-party brand's color." - **Brand Fill** — "Each button filled with the brand's color, white text and white mono icon." Card with **"Default"** badge is the default. Click **"Use this scheme"** to create the block and jump to the editor. ![Step 3 color scheme picker with Default badge highlighted](https://static.tantou.ai/images/tt-blocks/2026/05/87733f5f0efb81f5.png) ## Block type ↔ template enforcement The wizard enforces compatibility at two layers: - **Manifest filter (frontend)** — after picking placement, template list auto-filters to compatible presets - **Server validate (backend)** — submission re-validates placement × template compatibility See [Block types](/tt-blocks/concepts/widget-types) for cross-type switching prohibition. ---