Настройка Shopify Metafields для кастомных полей

Настройка Shopify Metafields для кастомных полей

Metafields — механизм расширения стандартной модели данных Shopify произвольными полями без разработки приложения. Доступны для продуктов, вариантов, коллекций, клиентов, заказов, страниц, блогов и магазина в целом.

Концепция namespace и key

Каждое метаполе идентифицируется парой namespace.key. Namespace — логическая группа (обычно имя приложения или домен данных), key — конкретное поле:

• custom.delivery_days — кастомное поле «Срок доставки»
• specifications.weight_net — характеристики, вес нетто
• seo.canonical_override — SEO-оверрайды
• loyalty.points_multiplier — поля программы лояльности

Стандартные namespace'ы Shopify: descriptors (для базовых описаний), facts (фактические данные).

Типы данных metafields

Типы *_reference и file_reference можно объявить списком (list.*) для хранения массива значений.

Создание metafield definitions через Admin

Admin > Settings > Custom data — интерфейс для создания определений метаполей. Определение фиксирует тип данных и делает поле доступным в карточках товаров/коллекций в Admin.

Без definition метаполе можно создать через API, но оно не будет отображаться в Admin UI и не будет доступно через Liquid (только через Storefront API).

Создание через GraphQL Admin API

// Создание metafield definition
const CREATE_DEFINITION = `
  mutation metafieldDefinitionCreate($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
        namespace
        key
        type { name }
      }
      userErrors { field message }
    }
  }
`;

await client.query({
  data: {
    query: CREATE_DEFINITION,
    variables: {
      definition: {
        name: "Срок доставки (дней)",
        namespace: "custom",
        key: "delivery_days",
        type: "number_integer",
        ownerType: "PRODUCT",
        validations: [
          { name: "min", value: "1" },
          { name: "max", value: "90" }
        ],
        pin: true  // Показывать вверху в карточке товара
      }
    }
  }
});

Массовое заполнение метаполей

Через Admin API для существующих продуктов:

// Установка метаполей для продукта
const SET_METAFIELDS = `
  mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
    metafieldsSet(metafields: $metafields) {
      metafields { id key namespace value }
      userErrors { field message }
    }
  }
`;

await client.query({
  data: {
    query: SET_METAFIELDS,
    variables: {
      metafields: [
        {
          ownerId: "gid://shopify/Product/123456789",
          namespace: "custom",
          key: "delivery_days",
          type: "number_integer",
          value: "3"
        },
        {
          ownerId: "gid://shopify/Product/123456789",
          namespace: "specifications",
          key: "warranty_years",
          type: "number_integer",
          value: "2"
        }
      ]
    }
  }
});

При массовом импорте — пакетировать по 25 метаполей на запрос (лимит API).

Вывод метаполей в Liquid-теме

Определённые через Admin metafield definitions доступны в Liquid напрямую:

{%- comment -%} sections/product-specs.liquid {%- endcomment -%}

{%- assign delivery = product.metafields.custom.delivery_days -%}
{%- assign warranty = product.metafields.specifications.warranty_years -%}
{%- assign related = product.metafields.custom.related_products.value -%}

<div class="product-specs">
  {%- if delivery != blank -%}
    <div class="spec-row">
      <span class="spec-label">Срок доставки:</span>
      <span class="spec-value">{{ delivery.value }} {{ delivery.value | pluralize: 'день', 'дня', 'дней' }}</span>
    </div>
  {%- endif -%}

  {%- if warranty != blank -%}
    <div class="spec-row">
      <span class="spec-label">Гарантия:</span>
      <span class="spec-value">{{ warranty.value }} г.</span>
    </div>
  {%- endif -%}
</div>

{%- comment -%} Список связанных продуктов (list.product_reference) {%- endcomment -%}
{%- if related != blank -%}
  <div class="related-products">
    <h3>Также подходит:</h3>
    {%- for related_product in related -%}
      <a href="{{ related_product.url }}">{{ related_product.title }}</a>
    {%- endfor -%}
  </div>
{%- endif -%}

Для метаполей типа rich_text_field — вывод через metafield.value:

{%- assign rich = product.metafields.custom.extended_description -%}
{%- if rich != blank -%}
  <div class="product-extended">
    {{ rich.value }}
  </div>
{%- endif -%}

Метаполя через Storefront API (для headless)

// GraphQL Storefront API
const PRODUCT_WITH_METAFIELDS = `
  query productByHandle($handle: String!) {
    product(handle: $handle) {
      title
      metafield(namespace: "custom", key: "delivery_days") {
        value
        type
      }
      variants(first: 10) {
        edges {
          node {
            metafield(namespace: "specifications", key: "color_hex") {
              value
            }
          }
        }
      }
    }
  }
`;

По умолчанию metafields не возвращаются в Storefront API — нужно явно указать namespace и key либо настроить Storefront API permissions в Admin.

Метаобъекты (Metaobjects)

Более мощная альтернатива — Metaobjects. Это кастомные типы контента (вроде CMS-типов) со своими полями, которые можно ссылочно использовать в метаполях продуктов.

Пример: создать тип Brand с полями name, logo, country, description, затем в продукте использовать метаполе типа metaobject_reference указывающее на экземпляр Brand.

{%- assign brand = product.metafields.custom.brand.value -%}
{%- if brand -%}
  <div class="brand-block">
    <img src="{{ brand.fields.logo.value | image_url: width: 120 }}" alt="{{ brand.fields.name.value }}">
    <span>{{ brand.fields.name.value }}</span>
    <span>{{ brand.fields.country.value }}</span>
  </div>
{%- endif -%}

Сроки

Настройка 10–20 metafield definitions с выводом в теме: 1–2 дня. Массовое заполнение метаполей через скрипт для существующего каталога (1000–10000 товаров): 1–3 дня включая написание скрипта маппинга и прогон. Разработка структуры на Metaobjects для сложного каталога (бренды, материалы, сертификаты): 3–5 дней.