SEO and tracking

Blanxer builds the product feed and the catalog sitemap. The site passes the sitemap through, renders metadata and JSON-LD from Blanxer's SEO fields, and loads the tracking tags the merchant set in Blanxer. SEO text is changed in Blanxer through the MCP, never hardcoded in the site.

#Files Blanxer builds

Both send Cache-Control: public, max-age=3600, stale-while-revalidate=86400. An unknown store id is HTTP 404.

Every link in them is absolute, on the store's site origin:

1. the saved site link (storefront_url), if set;
2. else the verified Blanxer custom domain;
3. else https://<sub>.blanxer.io.

So save the site link in Blanxer before you submit either file (blanxer_set_storefront_url, see Deploy). Before that, they point at the Blanxer-hosted site. The API uses a changed link on the next request, but HTTP caches (max-age=3600 plus stale-while-revalidate=86400) and the site's own /sitemap-catalog.xml (cached 3600 s) can serve the old links for an hour or more.

#What the catalog sitemap lists

• /, /products, /collections/new-arrivals
• /collections/<slug> for every category
• /product/<slug> for every Active, non-POS product
• /brand/<slug> for every brand
• /blogs, /blog/<slug>, and /blogs?category=<slug> for every category in check_domain.blog_categories (even one with no posts), when the store has published, indexable posts
• page-builder pages /p/<slug> only when no site link is saved; a custom site has none

This is why the paths are fixed (rule 10). It does not list /brands, /sale, /search, /forms/<slug> or any page you add. Those go in the site's own sitemap.

#What the product feed contains

Only Active, non-POS products. One <item> per product, or per variant for products with variants:

• g:id: the product _id, or <product_id>_<variant_id> for a variant, with g:item_group_id = the product _id;
• g:link: <origin>/product/<slug>;
• g:title, g:description, g:image_link (+ up to 10 g:additional_image_link), g:condition, g:availability (in stock / out of stock);
• g:brand: the product's brand, else the store's brand name or name;
• g:product_type: only when the product has categories;
• g:price and g:sale_price: when compare_at_price is above the selling price, g:price is compare_at_price (the regular price) and g:sale_price is the selling price; otherwise g:price is the selling price and there is no g:sale_price;
• g:quantity_to_sell_on_facebook.

Items without an image or a price above 0 are left out (Meta rejects them). The g:id values are the same ids the site must send as Meta content_ids (see Meta Pixel).

Don't build a feed or a catalog sitemap in the site (rule 10).

#The site's sitemap and robots

Google wants a sitemap on the same host as the pages it lists. That's why the site serves the catalog sitemap on its own host instead of linking to api.blanxer.com.

// app/sitemap-catalog.xml/route.ts
import { catalogSitemapRoute } from '@blanxer-dev/storefront/next';
export const GET = catalogSitemapRoute(); // fetches /public/sitemap/<store_id>.xml

// app/sitemap.xml/route.ts  (don't hand-write the index)
import { sitemapIndexRoute } from '@blanxer-dev/storefront/next';
export const GET = sitemapIndexRoute({ extra: ['/sitemap-pages.xml'] }); // leave out `extra` until you add that file

// app/robots.txt/route.ts
import { robotsRoute } from '@blanxer-dev/storefront/next';
export const GET = robotsRoute();

robotsRoute() allows everything, disallows /checkout, /cart, /payment/, /track/ and /cdn-cgi/ (add more with { disallow: [...] }), and ends with Sitemap: <origin>/sitemap.xml. (The Blanxer-hosted storefront disallows /checkout and /cdn-cgi/.)

The origin comes from siteOrigin(): SITE_URL, else the saved storefront_url, else the request host.

#Page metadata

Use Next.js generateMetadata. The package's storeMetadata, productMetadata, categoryMetadata, brandMetadata and blogPostMetadata build these from the API data, so the merchant's SEO work in Blanxer shows up on the site. Titles get the template <title> | <store name> from the home page's metadata.

Where the Blanxer-hosted storefront differs: its product <title> is the name (seo_title only for og:title), its category description falls back to top_bar_text, and its brand title has no brand-name fallback (the package's fallback is an improvement).

• Home SEO comes from the store's landing page (GET /public/landing/<store_id>, read by getHomeSeo()). Only stores on a page-builder plan have one; otherwise the store name and description are used.
• The brand page's SEO fields come from GET /brand/public/products/<store_id>/<slug> as brand.page.seo_title, seo_description, seo_image.
• Every page: og:site_name = the store name, og:type (website, product, article), twitter:card = summary_large_image, and a canonical URL <origin><path> without query strings (except /blogs?category=).
• noindex on /cart, /checkout, /payment/success, /payment/failed, /track/[id], /search, and blog posts with no_index.
• On stores without a landing page, confirm the home title and description (the store name and description) with the merchant.

To improve the text, use the MCP: blanxer_audit_seo, then blanxer_update_product_status_seo, blanxer_bulk_update_products, blanxer_bulk_update_categories_seo, blanxer_update_brand. Confirm bulk changes first (rule 13). See MCP for your website.

#JSON-LD

Add structured data with the package's productJsonLd, organizationJsonLd and breadcrumbJsonLd, in a <script type="application/ld+json">.

Product (product pages), from real data only:

• @type: Product, @id: <url>#product, name, url, description (seo_description or the name), image (all image_urls);
• offers: @type: Offer, price (first variant's price, else the product's), priceCurrency: NPR, availability (InStock when continue_selling, or any stock), itemCondition: NewCondition, seller = the store;
• sku and gtin (barcode) when present, brand when the product has one, category from the first matching category name;
• aggregateRating only when review_count > 0: ratingValue = total_rating / review_count (the average, 1–5), reviewCount. (The Blanxer storefront puts the raw sum in ratingValue; don't copy that.)
• review entries only for real reviews.

Organization (home): name, url, logo, and sameAs with the social links that are set.

BreadcrumbList (product, category, brand): Home → Category or Brand → Product.

Never add placeholder ratings, prices or reviews (rule 8).

#Search Console verification

1. The merchant adds the site in Google Search Console as a URL-prefix property (https://mystore.com/) and picks HTML tag. They copy the tag or just its content value.
2. You call blanxer_set_site_verification { google_verification_code: "<the tag or the content value>" } through the MCP. Blanxer stores it in the meta_tags plugin as {n: "google-site-verification", c: "<code>"}.
3. The site renders every meta_tags entry as <meta name={n} content={c}> on the home page. verificationMetadata(store) from the package returns it as Next.js metadata.verification / metadata.other.
4. Wait about a minute for the caches, check the tag is in the page source, then click Verify.
5. Submit https://<site>/sitemap.xml under Sitemaps.

A Domain property (verified with a DNS TXT record) works too: the merchant adds the TXT record in their own Cloudflare DNS. Then no meta tag is needed.

#Google Analytics, Tag Manager and Clarity

The ids come from check_domain.plugins, an array of {name, details}:

• ga: a GA4 id (G-...);
• gtm: a Tag Manager id (GTM-...);
• clarity: a Microsoft Clarity id.

Set or change GA/GTM with blanxer_set_site_verification { ga_id } or { gtm_id }. The package's <Pixel> loads GA4, GTM, Clarity and the Meta Pixel from these plugins, each only when its id is present and after the page is interactive. Never hardcode an id in the site.

#Meta Pixel and Conversions API

• Pixel: when plugins has fb_pixel, load Meta's fbevents.js with that id and track PageView on every route change.
• Conversions API relay: when plugins has meta_capi (its details is just true; the access token stays on Blanxer's server), every event is also sent to Blanxer, which forwards it to Meta. The relay goes through Blanxer's domain, so ad blockers don't drop it.

The package's Pixel component and trackEvent do both.

#Events

content_ids must match the feed's g:id: <product_id>_<variant_id> for a variant line, the product _id otherwise. Otherwise Meta's catalog ads can't match events to products.

#The relay call

POST /public/meta-event/<store_id>
Content-Type: application/json

{ "event_name": "AddToCart", "event_id": "<uuid, the same one passed to fbq as eventID>",
  "event_source_url": "https://mystore.com/product/pashmina-shawl",
  "fbp": "<_fbp cookie>", "fbc": "<_fbc cookie>",
  "custom_data": { "content_ids": ["..._..."], "content_type": "product", "value": 2500, "currency": "NPR" } }

• event_name is one of ViewContent, AddToCart, InitiateCheckout, Purchase. Add email and phone only for Purchase.
• custom_data keeps only value, currency, content_type, content_ids (≤ 200), contents and num_items. Other keys, such as content_name, are dropped by the relay (the browser Pixel still gets them).
• A valid event always gets {"success": true}: also when the store has no meta_capi, and when forwarding to Meta fails. A malformed body is HTTP 400 (validation error).
• Limit: 100 per minute per IP.
• Send it from the browser with fetch(..., { keepalive: true }) and don't wait for it. Blanxer forwards the caller's IP and user agent to Meta, so a server-side call would report the Worker instead of the shopper.

#Purchase without double counting

• The checkout creates one event_id per order and sends it in the order's meta block with fbp, fbc and event_source_url.
• COD: Blanxer's server sends the CAPI Purchase when the order is created. The browser fires only the Pixel Purchase, with the same event_id.
• Online payments: /payment/success fires the Pixel and the relay with that event_id.
• Meta dedupes on event_id.

#Register the product feed

After the site link is saved:

• Meta Commerce Manager: Catalog → Data sources → Data feed → scheduled feed from URL https://api.blanxer.com/public/product-feed/<store_id>.xml, hourly or daily.
• Google Merchant Center: Products → Feeds → scheduled fetch of the same URL.

Meta's and Google's crawlers fetch the feed from api.blanxer.com directly. That hasn't been checked against Cloudflare's bot rules yet, so after adding it, check the feed fetched without errors (Commerce Manager / Merchant Center shows the fetch status).

blanxer_get_store_context returns the feed and sitemap URLs (product_feed_url, sitemap_url) only once a site link is saved. They arrive with the BlanxerAPI release of the MCP.