token product schema (#3113)

Author: isstuev

lib/metadata/__snapshots__/generate.test.ts.snap

@@ -4,6 +4,7 @@ exports[`generates correct metadata for: dynamic route 1`] = `
 {
   "canonical": undefined,
   "description": "View transaction 0x12345 on Blockscout (Blockscout) Explorer",
+  "jsonLd": undefined,
   "opengraph": {
     "description": "",
     "imageUrl": "",
@@ -17,6 +18,24 @@ exports[`generates correct metadata for: dynamic route with API data 1`] = `
 {
   "canonical": undefined,
   "description": "0x12345, balances and analytics on the Blockscout (Blockscout) Explorer",
+  "jsonLd": {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    "brand": {
+      "@type": "Brand",
+      "name": "Tether",
+    },
+    "description": "USDT is a stablecoin",
+    "logo": "https://example.com/usdt.png",
+    "name": "USDT",
+    "offers": {
+      "@type": "Offer",
+      "price": "1.00",
+      "priceCurrency": "USD",
+    },
+    "productID": "0x12345",
+    "url": "http://localhost:3000/token/0x12345",
+  },
   "opengraph": {
     "description": "",
     "imageUrl": "",
@@ -30,6 +49,7 @@ exports[`generates correct metadata for: static route 1`] = `
 {
   "canonical": "http://localhost:3000/txs",
   "description": "Open-source block explorer by Blockscout. Search transactions, verify smart contracts, analyze addresses, and track network activity. Complete blockchain data and APIs for the Blockscout (Blockscout) Explorer network.",
+  "jsonLd": undefined,
   "opengraph": {
     "description": "",
     "imageUrl": "http://localhost:3000/static/og_image.png",

lib/metadata/generate.test.ts

@@ -33,7 +33,16 @@ const TEST_CASES = [
       pathname: '/token/[hash]',
       query: { hash: '0x12345' },
     },
-    apiData: { symbol_or_name: 'USDT' },
+    apiData: {
+      symbol_or_name: 'USDT',
+      address_hash: '0x12345',
+      description: 'USDT is a stablecoin',
+      projectName: 'Tether',
+      icon_url: 'https://example.com/usdt.png',
+      exchange_rate: '1.00',
+      name: 'USDT',
+      symbol: 'USDT',
+    },
   } as TestCase<'/token/[hash]'>,
 ];
 

lib/metadata/generate.ts

@@ -8,6 +8,7 @@ import getNetworkTitle from 'lib/networks/getNetworkTitle';
 import { currencyUnits } from 'lib/units';
 
 import compileValue from './compileValue';
+import generateProductSchema from './generateProductSchema';
 import getCanonicalUrl from './getCanonicalUrl';
 import getPageOgType from './getPageOgType';
 import * as templates from './templates';
@@ -29,6 +30,7 @@ export default function generate<Pathname extends Route['pathname']>(route: Rout
   const description = compileValue(templates.description.make(route.pathname, Boolean(apiData)), params);
 
   const pageOgType = getPageOgType(route.pathname);
+  const jsonLd = generateProductSchema(route, apiData);
 
   return {
     title: title,
@@ -39,5 +41,6 @@ export default function generate<Pathname extends Route['pathname']>(route: Rout
       imageUrl: pageOgType !== 'Regular page' ? config.meta.og.imageUrl : '',
     },
     canonical: getCanonicalUrl(route.pathname),
+    jsonLd,
   };
 }

lib/metadata/generateProductSchema.ts

@@ -0,0 +1,67 @@
+import type { ProductSchema, ApiData } from './types';
+import type { RouteParams } from 'nextjs/types';
+
+import type { Route } from 'nextjs-routes';
+
+import config from 'configs/app';
+
+/**
+ * Generates Product schema (JSON-LD) for token pages
+ * Returns undefined for non-token pages or when data is not available
+ */
+export default function generateProductSchema<Pathname extends Route['pathname']>(
+  route: RouteParams<Pathname>,
+  apiData: ApiData<Pathname>,
+): ProductSchema | undefined {
+  // Only generate for token pages
+  if (route.pathname !== '/token/[hash]') {
+    return undefined;
+  }
+
+  // Only generate if we have token data
+  if (!apiData || typeof apiData !== 'object') {
+    return undefined;
+  }
+
+  const tokenData = apiData as ApiData<'/token/[hash]'>;
+  if (!tokenData) {
+    return undefined;
+  }
+
+  const hash = typeof route.query?.hash === 'string' ? route.query.hash : undefined;
+  if (!hash) {
+    return undefined;
+  }
+
+  const baseUrl = config.app.baseUrl;
+  const tokenUrl = `${ baseUrl }/token/${ hash }`;
+
+  const schema: ProductSchema = {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name: tokenData.name || tokenData.symbol || undefined,
+    description: tokenData.description || undefined,
+    logo: tokenData.icon_url || undefined,
+    url: tokenUrl,
+    productID: tokenData.address_hash,
+  };
+
+  if (tokenData.projectName) {
+    schema.brand = {
+      '@type': 'Brand',
+      name: tokenData.projectName,
+    };
+  }
+
+  // Only include offers if we have a valid price
+  // Schema.org requires valid price data when including an Offer
+  if (tokenData.exchange_rate) {
+    schema.offers = {
+      '@type': 'Offer',
+      price: tokenData.exchange_rate,
+      priceCurrency: 'USD',
+    };
+  }
+
+  return schema;
+}

lib/metadata/types.ts

@@ -7,13 +7,32 @@ import type { Route } from 'nextjs-routes';
 export type ApiData<Pathname extends Route['pathname']> =
 (
     Pathname extends '/address/[hash]' ? { domain_name: string } :
-    Pathname extends '/token/[hash]' ? TokenInfo & { symbol_or_name: string } :
+    Pathname extends '/token/[hash]' ? TokenInfo & { symbol_or_name: string; description?: string; projectName?: string } :
     Pathname extends '/token/[hash]/instance/[id]' ? { symbol_or_name: string } :
     Pathname extends '/apps/[id]' ? { app_name: string } :
     Pathname extends '/stats/[id]' ? LineChart['info'] :
     never
 ) | null;
 
+export interface ProductSchema {
+    '@context': string;
+    '@type': 'Product';
+    name?: string;
+    description?: string;
+    logo?: string;
+    url?: string;
+    productID?: string;
+    offers?: {
+        '@type': 'Offer';
+        price?: string;
+        priceCurrency?: string;
+    };
+    brand?: {
+        '@type': 'Brand';
+        name?: string;
+    };
+}
+
 export interface Metadata {
     title: string;
     description: string;
@@ -23,4 +42,5 @@ export interface Metadata {
         imageUrl?: string;
     };
     canonical: string | undefined;
+    jsonLd?: ProductSchema;
 }

lib/metadata/update.ts

@@ -5,9 +5,31 @@ import type { Route } from 'nextjs-routes';
 
 import generate from './generate';
 
+const JSON_LD_SCRIPT_ID = 'blockscout-product-schema';
+
 export default function update<Pathname extends Route['pathname']>(route: RouteParams<Pathname>, apiData: ApiData<Pathname>) {
-  const { title, description } = generate(route, apiData);
+  const { title, description, jsonLd } = generate(route, apiData);
 
   window.document.title = title;
   window.document.querySelector('meta[name="description"]')?.setAttribute('content', description);
+
+  // Update or create JSON-LD script tag for Product schema
+  if (jsonLd) {
+    let scriptElement = window.document.getElementById(JSON_LD_SCRIPT_ID) as HTMLScriptElement | null;
+
+    if (!scriptElement) {
+      scriptElement = window.document.createElement('script');
+      scriptElement.id = JSON_LD_SCRIPT_ID;
+      scriptElement.type = 'application/ld+json';
+      window.document.head.appendChild(scriptElement);
+    }
+
+    scriptElement.textContent = JSON.stringify(jsonLd);
+  } else {
+    // Remove JSON-LD script if it exists but schema is not needed
+    const existingScript = window.document.getElementById(JSON_LD_SCRIPT_ID);
+    if (existingScript) {
+      existingScript.remove();
+    }
+  }
 }

ui/pages/Token.tsx

@@ -108,12 +108,24 @@ const TokenPageContent = () => {
     handler: handleTotalSupplyMessage,
   });
 
+  const verifiedInfoQuery = useApiQuery('contractInfo:token_verified_info', {
+    pathParams: { hash: tokenQuery.data?.address_hash, chainId: config.chain.id },
+    queryOptions: { enabled: Boolean(tokenQuery.data) && !tokenQuery.isPlaceholderData && config.features.verifiedTokens.isEnabled },
+  });
+
   useEffect(() => {
-    if (tokenQuery.data && !tokenQuery.isPlaceholderData && !config.meta.seo.enhancedDataEnabled) {
-      const apiData = { ...tokenQuery.data, symbol_or_name: tokenQuery.data.symbol ?? tokenQuery.data.name ?? '' };
+    // even if config.meta.seo.enhancedDataEnabled is enabled, we don't fetch contract info for the project description
+    // so we need to update the metadata anyway.
+    if (tokenQuery.data && !tokenQuery.isPlaceholderData && !verifiedInfoQuery.isPlaceholderData) {
+      const apiData = {
+        ...tokenQuery.data,
+        symbol_or_name: tokenQuery.data.symbol ?? tokenQuery.data.name ?? '',
+        description: verifiedInfoQuery.data?.projectDescription,
+        projectName: verifiedInfoQuery.data?.projectName,
+      };
       metadata.update({ pathname: '/token/[hash]', query: { hash: tokenQuery.data.address_hash } }, apiData);
     }
-  }, [ tokenQuery.data, tokenQuery.isPlaceholderData ]);
+  }, [ tokenQuery.data, tokenQuery.isPlaceholderData, verifiedInfoQuery.isPlaceholderData, verifiedInfoQuery.data ]);
 
   const hasData = (tokenQuery.data && !tokenQuery.isPlaceholderData) && (addressQuery.data && !addressQuery.isPlaceholderData);
   const hasInventoryTab = tokenQuery.data?.type && NFT_TOKEN_TYPE_IDS.includes(tokenQuery.data.type);
@@ -266,7 +278,12 @@ const TokenPageContent = () => {
     <>
       <TextAd mb={ 6 }/>
 
-      <TokenPageTitle tokenQuery={ tokenQuery } addressQuery={ addressQuery } hash={ hashString }/>
+      <TokenPageTitle
+        tokenQuery={ tokenQuery }
+        addressQuery={ addressQuery }
+        verifiedInfoQuery={ verifiedInfoQuery }
+        hash={ hashString }
+      />
 
       <TokenDetails tokenQuery={ tokenQuery }/>
 

ui/token/TokenPageTitle.tsx

@@ -3,13 +3,12 @@ import type { UseQueryResult } from '@tanstack/react-query';
 import React from 'react';
 
 import type { Address } from 'types/api/address';
-import type { TokenInfo } from 'types/api/token';
+import type { TokenInfo, TokenVerifiedInfo as TTokenVerifiedInfo } from 'types/api/token';
 import type { EntityTag } from 'ui/shared/EntityTags/types';
 
 import config from 'configs/app';
 import useAddressMetadataInfoQuery from 'lib/address/useAddressMetadataInfoQuery';
 import type { ResourceError } from 'lib/api/resources';
-import useApiQuery from 'lib/api/useApiQuery';
 import { useMultichainContext } from 'lib/contexts/multichain';
 import { getTokenTypeName } from 'lib/token/tokenTypes';
 import { Tooltip } from 'toolkit/chakra/tooltip';
@@ -33,18 +32,14 @@ const PREDEFINED_TAG_PRIORITY = 100;
 interface Props {
   tokenQuery: UseQueryResult<TokenInfo, ResourceError<unknown>>;
   addressQuery: UseQueryResult<Address, ResourceError<unknown>>;
+  verifiedInfoQuery: UseQueryResult<TTokenVerifiedInfo, ResourceError<unknown>>;
   hash: string;
 }
 
-const TokenPageTitle = ({ tokenQuery, addressQuery, hash }: Props) => {
+const TokenPageTitle = ({ tokenQuery, addressQuery, verifiedInfoQuery, hash }: Props) => {
   const multichainContext = useMultichainContext();
   const addressHash = !tokenQuery.isPlaceholderData ? (tokenQuery.data?.address_hash || '') : '';
 
-  const verifiedInfoQuery = useApiQuery('contractInfo:token_verified_info', {
-    pathParams: { hash: addressHash, chainId: config.chain.id },
-    queryOptions: { enabled: Boolean(tokenQuery.data) && !tokenQuery.isPlaceholderData && config.features.verifiedTokens.isEnabled },
-  });
-
   const addressesForMetadataQuery = React.useMemo(() => ([ hash ].filter(Boolean)), [ hash ]);
   const addressMetadataQuery = useAddressMetadataInfoQuery(addressesForMetadataQuery);