Sitemap

Giới thiệu

Tính năng Submit Sitemap cho phép developer cung cấp danh sách các pagePath trong Mini App để hệ thống có thể: Crawl nội dung trang → Chuẩn hóa dữ liệu → Index dữ liệu vào hệ thống tìm kiếm

Tại sao cần submit sitemap?

Việc submit sitemap mang lại các lợi ích sau:

• Index dữ liệu cho hệ thống tìm kiếm nhanh chóng và đơn giản: Sitemap cung cấp danh sách các trang trong Mini App để hệ thống có thể crawl nội dung, trích xuất dữ liệu và index vào hệ thống Search.
• Làm giàu dữ liệu tìm kiếm: Sitemap giúp hệ thống Search phát hiện thêm nhiều nội dung trong Mini App nhờ đó kết quả tìm kiếm sẽ đầy đủ và phong phú hơn.
• Cập nhật dữ liệu tìm kiếm nhanh hơn: Khi nội dung trong sitemap thay đổi, crawler sẽ tự động phát hiện thay đổi để index lại nội dung hiển thị trên trang kết quả tìm kiếm. Đảm bảo search index luôn được đồng bộ với nội dung Mini App.

THÔNG TIN

Upload sitemap là một trong những phương thức index dữ liệu nhanh chóng và dễ triển khai nhất cho hệ thống tìm kiếm.

Quick Start

Để submit sitemap cho Mini App:

1. Tạo sitemap file chứa danh sách pagePath

Ví dụ:

/product/1
/product/2
/store/1
/store/2

2. Thao tác trên Console

• Tại trang thông tin chi tiết của Mini App → Chọn tab Cấu hình tìm kiếm > Sitemap
• Tại trang Sitemap, NPT có thể submit sitemap bằng 2 cách:
  • Upload file sitemap
  • Cung cấp sitemap URL. Ví dụ: https://org_name.vn/miniapp-sitemap.xml

Hệ thống sẽ: Validate sitemap → Crawl các page → Index dữ liệu vào Search

GHI CHÚ

• Thời gian index có thể mất vài phút đến vài giờ tùy theo số lượng page
• Hệ thống có schedule daily crawl và trigger crawl khi developer submit sitemap mới

Phương thức submit sitemap

Hiện tại hệ thống hỗ trợ 2 cách submit sitemap

1. Khai báo sitemap URL

Developer có thể cung cấp một đường dẫn sitemap cố định để hệ thống tự động crawl.

Ví dụ:

https://org_name.vn/miniapp-sitemap.xml

Hệ thống sẽ định kỳ truy cập đường dẫn này để cập nhật dữ liệu mới.

2. Upload sitemap

Developer có thể upload trực tiếp file sitemap.

Các định dạng file được hỗ trợ bao gồm:

• TXT
• XML

Tiêu chuẩn thiết kế

1. Sitemap dạng TXT

Đối với định dạng TXT, mỗi dòng tương ứng với một pagePath trong Mini App. Ví dụ:

/product/1
/product/2
/product/3
/store/1
/store/2
/store/3

File sitemap TXT cần tuân theo các quy tắc sau:

1. Không được phép là file rỗng

File phải chứa ít nhất 1 pagePath hợp lệ

2. Tuân thủ quy tắc pagePath

• Không chấp nhận đường dẫn bắt đầu bằng scheme hoặc protocol. Ví dụ: https://, vapp://
• Mỗi dòng là một đường dẫn (pagePath) trong mini app
• Mỗi đường dẫn phải bắt đầu bằng /

Ví dụ:

/product/1
/product/2
/store/3

3. Sử dụng các ký tự được cho phép

Các thành phần trong đường dẫn phải tuân thủ các quy tắc sau:

Ví dụ: /addresses?service_type=RIDE-TRIP%2CRIDE-ROUTE&service_group=1

Thành phần	Quy tắc
Path Ví dụ: /addresses	Cho phép - Letters & Numbers: A-Z, a-z, 0-9 - Punctuation: - hyphen, _ underscore, . dot - Special characters: / forward slash, , # hash
Key (param name) Ví dụ: service_type, service_group	Cho phép - Letters & Numbers: A-Z, a-z, 0-9 - Punctuation: - hyphen, _ underscore
Giá trị (param value) Ví dụ: RIDE-TRIP%2CRIDE-ROUTE	Phải luôn URL-encode

Lưu ý:

• Hệ thống sẽ bỏ qua các dòng blank hoặc empty line khi crawl
• Sitemap phải chứa ít hơn 10,000 URLs (không bao gồm các dòng trống)

2. Sitemap dạng XML

Đối với định dạng XML, hiện tại chỉ hỗ trợ subset cơ bản của tiêu chuẩn này. Ví dụ:

<?xml version="1.0" encoding="UTF-8"?>
<urlset>
  <url>
    <loc>/product/?id=1212</loc>
    <lastmod>2022-06-04</lastmod>
  </url>
  <url>
    <loc>/store/?id=22</loc>
    <lastmod>2022-06-04</lastmod>
  </url>
</urlset>

Các thành phần bắt buộc

XML sitemap phải bao gồm:

Tag	Description
<urlset>	Root element của sitemap
<url>	Một entry cho mỗi page
<loc>	Chứa pagePath

File sitemap XML cần tuân theo các quy tắc sau:

1. Không được phép là file rỗng

File phải chứa ít nhất 1 URL hợp lệ

2. Khai báo chuẩn XML

File phải bắt đầu bằng:

<?xml version="1.0" encoding="UTF-8"?>

3. Nội dung chính phải nằm trong <urlset>

• Bao gồm thẻ <url> cho mỗi pagePath

• Bao gồm thẻ <loc> chứa giá trị đường dẫn cho mỗi thẻ <url>
  Ví dụ:

  <url>
    <loc>/product/1</loc>
  </url>

• Giá trị trong <loc> phải tuân theo các quy tắc sau:

  • Không được rỗng
  • Phải bắt đầu bằng /
  • Không chứa scheme hoặc protocol. Ví dụ: https://, vapp://

4. Sử dụng các ký tự được cho phép

Các thành phần trong đường dẫn phải tuân thủ các quy tắc sau:

Ví dụ: /addresses?service_type=RIDE-TRIP%2CRIDE-ROUTE&service_group=1

Thành phần	Quy tắc
Path Ví dụ: /addresses	Cho phép - Letters & Numbers: A-Z, a-z, 0-9 - Punctuation: - hyphen, _ underscore, . dot - Special characters: / forward slash, # hash
Key (param name) Ví dụ: service_type, service_group	Cho phép - Letters & Numbers: A-Z, a-z, 0-9 - Punctuation: - hyphen, _ underscore
Giá trị (param value) Ví dụ: RIDE-TRIP%2CRIDE-ROUTE	Phải luôn URL-encode

Lưu ý: Sitemap phải chứa ít hơn 10,000 URLs (không bao gồm các dòng trống)

Cập nhật Mini App

Để Sitemap có thể hoạt động đúng, bên Mini App cần khai báo thông tin schema. Structured Data giúp hệ thống Search hiểu nội dung page và cải thiện chất lượng index.

Có 2 cách để khai báo:

1. Khai báo bằng config

NPT có thể định nghĩa 1 file SEO config theo format sau, crawler sẽ đọc config và lấy được nội dung schema:

• Tạo file seoConfig.ts ở root folder với nội dung mẫu như bên dưới:

/* eslint-disable @typescript-eslint/no-explicit-any */
export interface SeoContext {
  params: Record<string, string>; // /product/:id -> params.id
  query: Record<string, string>; // ?sku=abc -> query.sku
  path: string;
}
export interface SeoResult {
  title: string;
  description?: string;
  image?: string;
  schema?: Record<string, any>;
}
export default {
  // Đường dẫn tới page trong sitemap, có thể có nhiều path khác nhau
  '/:category/:product': async (req: SeoContext): Promise<SeoResult> => {
    const { path, query } = req;
    const url = encodeURIComponent(path.startsWith('/') ? path.slice(1) : path);
    const rs = await fetch(
      `https://api.miniapp.vn?url=${url}&provinceId=1027` // Mini App API
    );
    const data = (await rs.json()).data;
    // Thông tin này sẽ tuỳ do các Mini App tự định nghĩa theo chuẩn của schema.org
    return {
      title: data.name,
      description: '',
      image: data.avatar,
      schema: {
        '@context': 'https://schema.org',
        '@type': 'Product',
        name: data.name,
        description: data.name,
        image: data.avatar,
        sku: query.sku,
        reviewRating: {
          '@type': 'Rating',
          ratingValue: data.scoreRating,
        },
      },
    };
  },
};

• Khai báo seoConfig trong file app-config.json

{
  "appIdentifier": "app-demo.v-app.vn",
  "appName": "App Demo",
  "h5App": "YES",
  "seoConfig": "./seoConfig.ts", // Thêm thuộc tính này,
  ...
}

2. Khai báo trong component

NPT có thể thêm 1 component vào page có trong sitemap để tạo ra script schema.

Ví dụ SEO component mẫu:

import { useEffect, useId, type FC } from 'react'

export type TSeoProps = {
  metadata: any
}

export const SeoMetadataId = 'vsf-metadata'

export const Seo: FC<TSeoProps> = ({ metadata }) => {
  const metadataString = JSON.stringify(metadata, null, 2)
  const devId = useId()

  useEffect(() => {
    let element = document.querySelector(
      `[dev-id="${devId}"]`,
    ) as HTMLScriptElement | null

    if (!element) {
      element = document.createElement('script')
      element.id = SeoMetadataId
      element.type = 'application/ld+json'
      element.setAttribute('dev-id', devId)
      document.head.appendChild(element)
    }

    element.innerHTML = metadataString

    return () => {
      const element = document.getElementById(SeoMetadataId)
      element?.remove()
    }
  }, [metadataString, devId])

  return null
}

Cách dùng trong 1 page:

export const Page = () => {
  return (
    <>
      <Seo
        metadata={{
          '@type': 'WebApplication',
          name: 'name_value',
          description: 'description_value',
          applicationCategory: 'category_value',
          author: 'SEO Demo',
          url: 'https://vsf.com',
          image: 'image_url',
          screenshot: 'image_url',
          aggregateRating: {
            '@type': 'AggregateRating',
            ratingValue: '4.7',
            ratingCount: '123',
          },
        }}
      />
      <PageComponentCode />
    </>
  );
};

Khi page đó được render, thì html sẽ có thẻ script đó:

Crawler sẽ đọc component có id là vsf-metadata để lấy thông tin, do đó component của NPT phải đảm bảo chứa json đúng structure và đúng id.

Một số lưu ý

1. Không cần khai báo appId trong sitemap

Không cần đặt appId vào sitemap, metadata này sẽ tự truyền từ BE.

2. Chỉ khai báo các trang cần index

Không nên đưa vào sitemap các trang như:

/login
/cart
/profile
/payment

3. Tránh duplicate pagePath

Không nên khai báo cùng một pagePath nhiều lần.

4. Dữ liệu được index vào search dựa trên file sitemap mới nhất

Hệ thống sẽ crawl dữ liệu để index cho Search dựa vào file sitemap được submit gần nhất thông qua luồng upload file hoặc add URL.