Skip to content
Appifire
Docs
App Embed Settings Plan

App Embed Settings Plan

Plan for exposing widget settings inside Shopify Theme Editor app embed.

App Embed Settings Plan

Section titled “App Embed Settings Plan”

Status: IMPLEMENTED (simplified model: embed activation only + DB-first appearance settings).

1) Goal

Section titled “1) Goal”

Allow merchants to configure key chat widget options directly from Shopify Theme Editor app embed settings, while keeping your in-app Admin pages as the source of advanced configuration.

Target editor location:

  • Online Store -> Themes -> Customize -> App embeds -> Appifire AI Chat

2) Why this matters

Section titled “2) Why this matters”
  • Merchants expect storefront display controls in Theme Editor.
  • Faster activation and simpler onboarding (toggle + visual options in one place).
  • Reduces context switching between app admin and theme customizer.
  • Keeps app aligned with common Shopify app UX conventions.

3) Settings model (simplified)

Section titled “3) Settings model (simplified)”

Theme Editor app embed now exposes no storefront controls.

  • Merchant action in Theme Editor: enable the AppiFire Chat embed and save.
  • No title/message/color/position fields are configured in Theme Editor.

All other widget settings are managed in app admin only:

  • Widget title
  • Welcome message
  • Brand color
  • Bubble position
  • Business/operational settings (billing, limits, data sync, knowledge, etc.)

4) Source of truth and precedence

Section titled “4) Source of truth and precedence”

To avoid conflicts between Admin app settings and Theme Editor app embed settings, the implementation uses a DB-first runtime model.

Implemented model (DB source of truth)

Section titled “Implemented model (DB source of truth)”
  1. Database value (shops table) is canonical.
  2. Admin edits write directly to DB.
  3. Storefront widget runtime fetches DB settings from GET /api/widget-settings.
  4. Code defaults are used only when DB/client values are missing or invalid.

Data strategy (implemented)

Section titled “Data strategy (implemented)”
  • Keep current DB fields (no destructive change).
  • Read embed settings in storefront runtime (window.AppifireChat.settings) as optional metadata only.
  • Fetch DB settings from GET /api/widget-settings and apply them for appearance values (title, welcome message, brand color, bubble position).
  • Result: merchants manage all widget behavior in app admin, and use Theme Editor only to activate embed placement.

5) UX behavior

Section titled “5) UX behavior”

In Theme Editor

Section titled “In Theme Editor”
  • Merchant enables embed and clicks Save in theme customizer.
  • Storefront preview updates immediately.

In App Admin (Appearance/Settings pages)

Section titled “In App Admin (Appearance/Settings pages)”
  • Keep existing forms.
  • Add helper copy:
    • “App admin is the source of truth. Theme Editor embed fields can remain empty.”
  • Keep deep link action: “Open Theme Editor (App embeds)”.
Section titled “Navigation links”

Add quick links so merchants know where to configure related features outside embed display settings:

  • Appearance (/app/appearance) — visual widget settings and storefront visibility.
  • Knowledge Hub (/app/knowledge) — website/business content used for responses.
  • Chats (/app/chat-logs) — review real conversations and optimize copy.
  • Billing (/app/billing) — plan, usage, and credit balance management.

Suggested placement:

  • In the app embed help/description text, include module navigation shortcuts back to app admin:
    • Dashboard (/apps/appifire-ai-chat/app)
    • Chats (/apps/appifire-ai-chat/app/chat-logs)
    • Data Sync (/apps/appifire-ai-chat/app/data-sync)
    • Knowledge Hub (/apps/appifire-ai-chat/app/knowledge)
    • Settings (/apps/appifire-ai-chat/app/settings)
    • Appearance (/apps/appifire-ai-chat/app/appearance)
    • Billing & Usage (/apps/appifire-ai-chat/app/billing)
  • In the Appearance page, show clear links:
    • Dashboard (/app)
    • Chats (/app/chat-logs)
    • Data Sync (/app/data-sync)
    • Knowledge Hub (/app/knowledge)
    • Settings (/app/settings)
    • Appearance (/app/appearance)
    • Billing & Usage (/app/billing)
  • Optional: in Theme Editor docs/help tooltip with “Open App Admin” deep links.

6) Technical implementation plan

Section titled “6) Technical implementation plan”

Step 1: Define schema in extension

Section titled “Step 1: Define schema in extension”
  • Keep app embed extension schema informational-only:
    • no runtime behavior controls in embed settings
    • include guidance text + admin module links

Step 2: Wire settings into storefront widget runtime

Section titled “Step 2: Wire settings into storefront widget runtime”
  • In widget liquid/script render path:
    • Read widget_enabled from Shopify-provided embed settings.
    • Pass these values into chat-widget.js config.
    • Resolve effective values with DB-first precedence for appearance settings.
    • Keep defaults as final fallback for invalid/missing values.

Step 3: Keep backward compatibility

Section titled “Step 3: Keep backward compatibility”
  • If merchant has not saved embed settings, existing DB-driven behavior remains unchanged.
  • No migration required for initial rollout.

Step 4: Admin app messaging

Section titled “Step 4: Admin app messaging”
  • Add subtle notice in Appearance page clarifying DB-first behavior.
  • Add “Open Theme Editor” action for convenience.
  • Add quick nav links to related pages: Appearance, Knowledge Hub, Chats, Billing.

Step 5: QA matrix

Section titled “Step 5: QA matrix”
  • New install: defaults render correctly.
  • Existing install with DB values: behavior unchanged.
  • Title + welcome + color + position + visibility update correctly from app admin.
  • Admin change appears on storefront immediately after save.
  • Theme Editor shows informational text with admin navigation links.
  • Mobile + desktop behavior remains stable.

7) Suggested release phases

Section titled “7) Suggested release phases”

Phase 1 (current)

Section titled “Phase 1 (current)”
  • Theme Editor used for embed activation only
  • Keep all appearance fields in app admin

Phase 2 (optional future)

Section titled “Phase 2 (optional future)”
  • If needed, expose selected advanced controls in Theme Editor after merchant feedback

8) Risks and mitigations

Section titled “8) Risks and mitigations”
  1. Confusion from duplicated settings
    • Mitigation: clear precedence note in admin UI.
  2. Theme-specific differences
    • Mitigation: test on Dawn + one custom theme.
  3. Unexpected mobile regressions
    • Mitigation: dedicated device QA checklist before release.

9) Final recommendation

Section titled “9) Final recommendation”

Keep Theme Editor embed simple with activation-only flow.
Keep visual, business, and operational controls inside app admin.
Keep shops table as source of truth for appearance values and provide clear in-app navigation guidance.

Home

01 Overview

AppiFire AI Chat — Product Plan & Architecture Options (A, B, C) Technology Overview & High-Level Tasks

01 Platform Foundation

Prerequisites (Detailed Plan) Shopify Setup — Partner Account, CLI, App, and Extension Shopify App Skeleton & Database (Detailed Plan)

02 Knowledge and RAG

Database Schema for RAG Product Sync & Ingestion RAG & Chat API RAG Data Sync (Products, Collections, Inventory, Blog Posts) + Order Lookup How the Codebase Uses Vector Information to Answer Users in Chat Website Knowledge from Web (GPT-4o Mini Search)

03 Billing and Usage

Billing & Usage Billing & Usage — Remaining Tasks Credits wallet: one-time purchases & subscription included credits Free Plan: Reply Cap and Monthly Reset Promo code functionality Shopify App Billing and Payments Tasks

04 Admin and Storefront

Admin Settings & Chat Widget Admin UI Design Plan — Bigger Font, Different Font, More Spacing, Styled Buttons AI Chats / Logs Screen Billing Screen Restructure Plan (Sales + Marketing Focus) Dashboard Plan — AppiFire AI Chat Design Guidelines and Styling System (Polaris + Tailwind Plan) Theme & Design System Timezone & Time Display Plan (Admin + Widget)

05 Chat Experience and Safety

Chat Guardrails Inspection Full Conversation History in OpenRouter Chat Order Lookup Reliability Guide Order Status Conversational Chat Flow Pre-Chat User Identity Form

06 Merchant Lifecycle

Register / Identify App Users (Paying Merchants) Uninstall: Record & Goodbye Email

07 Ops and Release

Deploy: Cloudflare Tunnel + Your Domain & App to appifire-ai-chat.appifire.com Launch & Publishing Guide Links Scheduled jobs, privacy & shop analytics Testing Up to Phase 2 (Product Sync & Ingestion)

08 Research and Ideas

App Names 20 Paid Feature Gaps — AppiFire AI Chat Roadmap Templates Shortlisted Top 30 Shopify App Ideas — High Demand, Buildable, Revenue Potential

09 Archive

100 AI Questions User Can Ask App Embed Settings Plan Chat Thread Identity and History Plan Plan: Free reply monthly reset & paid included credits delivery Future Todo List Promo Code Module Plan Reorganize Documents Support Feature Plan Talk to Human Flow Plan Welcome Email Plan (Brevo API)

10 Marketing and SEO

Article Writing Prompt Appifire SEO Topical Map Topical Map Prompt Appifire VS Pages VS Pages Prompt

11 Video Testimonial Collector

Post-Purchase Video Testimonial Collector — Detailed Product Plan Video Testimonial Collector - Implementation Blueprint Video Testimonial Collector - Pricing & Billing Options Delete All Existing Code and DB Tables (Boilerplate Cleanup) 05 — Storefront Widgets + Public Read API (Screen 8 & 8.1) 06 — Public Submission Page (Screen 13, `/t/:token`) 07 — Email/SMS Request Delivery Pipeline (Blueprint §4) 08 — Security, Compliance & Privacy (Blueprint §8) 09 — Submissions Inbox (Screen 5, `/app/testimonials`) 10 — Submission Detail & Moderation (Screen 6, `/app/testimonials/:id`) 11 — Published Content Manager (Screen 7, `/app/testimonials/published`) 12 — Moderation Settings (Screen 9, `/app/testimonials/moderation`) 13 — Requests Log (Blueprint Screen 10, `/app/testimonials/requests`) 14 — Analytics (Blueprint Screen 11, `/app/testimonials/analytics`) 15 — Billing & Usage (Blueprint Screen 12, `/app/testimonials/billing`) 16 — Templates (Screen 4, `/app/testimonial-templates`) 17 — Campaigns List (Screen 2, `/app/testimonial-campaigns`) 18 — Campaign Create/Edit (Screen 3, `/app/testimonial-campaigns/:id`) 19 — Dashboard (Screen 1, `/app`) 20 — Database Design & Migrations (Blueprint §5) 21 — Route & File Map Execution Plan (Blueprint §6) 22 — Integration & Processing Orchestration (Blueprint §7) 23 — Release Plan & Milestones (Blueprint §9) 24 — Build Notes Execution Standards (Blueprint §10) 25 — Core Modules Breakdown (Blueprint §2.2) 26 — Project Conventions Execution Guide (Blueprint §2.1) 27 — Product Scope Recommendation Execution (Blueprint §1) 28 — Admin Screens Information Architecture (Blueprint §3) 29 — Milestone 1 Delivery Plan (Blueprint §9.1) 30 — Milestone 2 Delivery Plan (Blueprint §9.2) 31 — Milestone 3 Delivery Plan (Blueprint §9.3) 32 — Email/SMS Operational Detail (Blueprint §4) 33 — TestimonialModerationLog Model & Audit Workflow (Blueprint §5.10) 34 — TestimonialDailyAnalytics Model & Rollup Jobs (Blueprint §5.11) 35 — TestimonialProductLink Model & Multi-Product Merchandising (Blueprint §5.9) 36 — TestimonialMediaAsset Model & Processing Pipeline (Blueprint §5.8) 37 — TestimonialSubmission Model & Lifecycle (Blueprint §5.7) 38 — TestimonialRequestEvent Model & Delivery Event Stream (Blueprint §5.6) 39 — TestimonialRequest Model & Scheduling Lifecycle (Blueprint §5.5) 40 — TestimonialTemplate Model & Resolution Rules (Blueprint §5.4) 41 — TestimonialCampaignProduct Model & Targeting Rules (Blueprint §5.3) 42 — TestimonialCampaign Model & Automation Rules (Blueprint §5.2) 43 — Shop Model Extension for Testimonials (Blueprint §5.1) 44 — Per-Product Collection Rule (Required) Implementation Plan 45 — Two Storefront Widgets (v1 Requirement, Screen 8.1)