Typesense for WooCommerce

Hướng dẫn DevOps

Cấu hình Typesense server, deployment pipeline, automation và troubleshooting.

Requirements

• WordPress ≥ 6.0
• WooCommerce ≥ 8.0
• PHP ≥ 8.0
• Typesense Server ≥ 28.0 (self-hosted)
• Composer (để cài typesense-php)

Cài đặt Typesense Server

Quick install (Linux x86_64)

# Tải và chạy Typesense single-node
curl -fsSL https://dl.typesense.org/releases/28.0/typesense-server-28.0-linux-amd64.tar.gz -o typesense.tar.gz
tar -xzf typesense.tar.gz
sudo mv typesense-server /usr/local/bin/

# Tạo data directory
sudo mkdir -p /var/lib/typesense
sudo useradd -r -s /bin/false typesense
sudo chown -R typesense:typesense /var/lib/typesense

# Systemd service
sudo tee /etc/systemd/system/typesense-server.service <<'EOF'
[Unit]
Description=Typesense Search Server
After=network.target

[Service]
Type=simple
User=typesense
Group=typesense
ExecStart=/usr/local/bin/typesense-server \
  --data-dir=/var/lib/typesense \
  --api-key=YOUR_API_KEY \
  --listen-port=8108 \
  --enable-cors
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now typesense-server

# Kiểm tra
curl http://localhost:8108/health

Docker (alternative)

docker run -d --name typesense \
  -p 8108:8108 \
  -v typesense-data:/data \
  typesense/typesense:28.0 \
  --data-dir /data \
  --api-key=YOUR_API_KEY \
  --listen-port 8108 \
  --enable-cors

Deployment pipeline

Add vào deployment script của dự án:

#!/bin/bash
# deploy-typesense-wc.sh
SITE_PATH=/var/www/example.com

# Clone/update plugin
if [ -d "$SITE_PATH/wp-content/plugins/typesense-for-woocommerce" ]; then
  cd "$SITE_PATH/wp-content/plugins/typesense-for-woocommerce"
  git pull origin main
else
  git clone https://github.com/codetot-web/typesense-for-woocommerce.git "$SITE_PATH/wp-content/plugins/typesense-for-woocommerce"
  cd "$SITE_PATH/wp-content/plugins/typesense-for-woocommerce"
fi

composer install --no-dev --optimize-autoloader

# Activate plugin
wp plugin activate typesense-for-woocommerce --path="$SITE_PATH"

# Verify Typesense connection
wp eval 'echo \TypesenseForWooCommerce\Plugin::get_instance()->get_client()->test_connection()["success"] ? "OK\\n" : "FAIL\\n";' --path="$SITE_PATH"

Typesense Resource Requirements

Automation

Các AJAX endpoints có thể dùng trong automation scripts:

WP-Cron schedule

# Cron: batch sync (nếu dùng tần suất tuỳ chỉnh)
0 */2 * * * wp cron event run ts4wc_batch_sync --path=/var/www/example.com

# Verify collection health
curl -X GET "http://localhost:8108/collections/woocommerce_products" \
  -H "X-TYPESENSE-API-KEY: YOUR_API_KEY" | jq '.num_documents'

Troubleshooting

Connection failed

Kiểm tra: Typesense server đang chạy (systemctl status typesense-server), port 8108 mở (firewall), API key đúng, CORS enabled.

Products không sync

Kiểm tra: "Enable Sync" được bật, Typesense API key có quyền document write, WP-Cron hoạt động (nếu dùng batch mode).

Search không trả về kết quả

Kiểm tra collection đã được tạo và có documents (curl /collections/woocommerce_products). Thử re-index từ admin.

Typesense server crash

Kiểm tra RAM — Typesense cần đủ RAM để giữ index trong memory. Xem resource requirements ở trên.

Marketing Toolkit

Tính năng, USP, messaging và tài liệu cho team Marketing.

Giới thiệu ngắn

Typesense for WooCommerce là plugin WordPress mã nguồn mở (GPLv2) giúp offload toàn bộ tìm kiếm và lọc sản phẩm WooCommerce từ MySQL sang Typesense — một search engine hiệu năng cao, cho tốc độ truy vấn dưới 50ms. Plugin hỗ trợ instant search, autocomplete dropdown, faceted filtering (danh mục, giá, thuộc tính), real-time sync, và graceful degradation khi Typesense không available.

USP (Unique Selling Points)

Target audiences

Competitor comparison

Content Plan & Use Cases

Ý tưởng bài viết, hướng dẫn, case study cho team Content.

Blog post ideas

Use cases

1. Cửa hàng thời trang (nhiều biến thể)

Hàng nghìn sản phẩm với nhiều size, màu sắc. Typesense cho phép lọc theo attribute (size, color) tức thời, không cần page reload.

2. Marketplace / Multi-vendor

Hàng trăm nghìn sản phẩm từ nhiều vendor. Typesense search + faceted filter giúp người mua tìm đúng sản phẩm trong vài mili giây.

3. Cửa hàng điện tử (nhiều thông số kỹ thuật)

Sản phẩm có nhiều thuộc tính (RAM, CPU, dung lượng). Typesense attribute filtering cho phép lọc chính xác theo thông số.

4. Site đa ngôn ngữ (WPML)

Typesense hỗ trợ multilingual search. Plugin tích hợp WPML/Polylang — search ra kết quả đúng ngôn ngữ người dùng.

5. LiteSoup hosting stack

Typesense là search engine được khuyến nghị cho LiteSoup. Plugin tích hợp sẵn, chỉ cần cài Typesense server là chạy.

Social media posts

API & Integration Reference

Tài liệu đầy đủ về AJAX endpoints, hooks, filters và integration API của Typesense for WooCommerce.

AJAX Endpoints

Plugin cung cấp các AJAX endpoints cho frontend và admin:

ts4wc_autocomplete (public)

PUBLIC — Tìm kiếm gợi ý sản phẩm cho autocomplete dropdown.

# Example response
{
  "success": true,
  "data": [
    {
      "product_id": 123,
      "title": "Áo thun nam",
      "sku": "AT-001",
      "price": "250000",
      "permalink": "https://...",
      "thumbnail_url": "https://...",
      "stock_status": "instock"
    }
  ]
}

ts4wc_test_connection (admin)

ADMIN — Kiểm tra kết nối đến Typesense server.

# Response mẫu
{ "success": true, "data": { "message": "Connection successful" } }

# Hoặc nếu lỗi
{ "success": false, "data": { "message": "Connection refused" } }

ts4wc_create_collection (admin)

ADMIN — Tạo hoặc cập nhật collection schema woocommerce_products.

ts4wc_sync_all (admin)

ADMIN — Đồng bộ toàn bộ sản phẩm lên Typesense.

WordPress Hooks

Filters

Actions

Collection Schema

Typesense collection woocommerce_products — 28 fields, default sorting by menu_order:

{
  "name": "woocommerce_products",
  "default_sorting_field": "menu_order",
  "enable_nested_fields": true,
  "fields": [
    { "name": "product_id",       "type": "int32",   "facet": false },
    { "name": "title",            "type": "string",  "facet": false },
    { "name": "description",      "type": "string",  "facet": false },
    { "name": "short_description","type": "string",  "facet": false },
    { "name": "sku",              "type": "string",  "facet": false },
    { "name": "slug",             "type": "string",  "facet": false },
    { "name": "price",            "type": "float",   "facet": true  },
    { "name": "sale_price",       "type": "float",   "facet": false },
    { "name": "regular_price",    "type": "float",   "facet": false },
    { "name": "on_sale",          "type": "bool",    "facet": true  },
    { "name": "in_stock",         "type": "bool",    "facet": true  },
    { "name": "stock_status",     "type": "string",  "facet": true  },
    { "name": "categories",       "type": "string[]","facet": true  },
    { "name": "category_ids",     "type": "int32[]", "facet": true  },
    { "name": "tags",             "type": "string[]","facet": true  },
    { "name": "attributes",       "type": "object",  "facet": false },
    { "name": "attribute_names",  "type": "string[]","facet": true  },
    { "name": "attribute_values", "type": "string[]","facet": true  },
    { "name": "type",             "type": "string",  "facet": true  },
    { "name": "featured",         "type": "bool",    "facet": true  },
    { "name": "rating",           "type": "float",   "facet": false },
    { "name": "review_count",     "type": "int32",   "facet": false },
    { "name": "menu_order",       "type": "int32",   "facet": false },
    { "name": "permalink",        "type": "string",  "facet": false },
    { "name": "thumbnail_url",    "type": "string",  "facet": false },
    { "name": "gallery_urls",     "type": "string[]","facet": false },
    { "name": "stock_quantity",   "type": "int32",   "facet": false },
    { "name": "brand",            "type": "string",  "facet": false }
  ]
}

Frontend JS Config

Plugin passes config to frontend via ts4wcConfig global:

{
  apiKey:       "YOUR_API_KEY",
  host:         "localhost",
  port:         8108,
  protocol:     "http",
  collection:   "woocommerce_products",
  searchPage:   "https://example.com/shop/",
  ajaxUrl:      "https://example.com/wp-admin/admin-ajax.php",
  nonce:        "FRONTEND_NONCE",
  isSearchPage: false,
  isShop:       true
}

Best practices