Налаштування Shopify Metafields для кастомних полів

Налаштування Shopify Metafields для користувацьких полів

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

Концепція namespace та key

Кожне метаполе ідентифікується парою namespace.key. Namespace — логічна група (зазвичай ім'я додатку або домен даних), key — конкретне поле:

• custom.delivery_days — користувацьке поле «Термін доставки»
• specifications.weight_net — характеристики, вага нетто
• seo.canonical_override — SEO-overrode
• 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 }} днів</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 днів.