Реалізація експорту товарів із сайту в Google Merchant Feed

Реалізація експорту товарів у Google Merchant Feed

Google Merchant Center приймає фіди у трьох форматах: XML (Atom 1.0 / RSS 2.0), текстовий TSV та API Content v2.1. Для автоматизації на боці сайту найбільш передбачуваним є XML-формат або пряма інтеграція через REST API. Помилки у фіді ведуть до дисапруву товарів та вимикання торгових кампаній у Google Ads.

Формати та вимоги

Google використовує стандарт атрибутів, задокументований у Product data specification. Обов'язкові атрибути для більшості країн:

XML-структура фіду

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0">
  <channel>
    <title>Мій магазин</title>
    <link>https://example.com</link>
    <description>Product feed</description>
    <item>
      <g:id>SKU-12345</g:id>
      <g:title>Samsung Galaxy S24 256GB Black</g:title>
      <g:description>Флагманський смартфон Samsung...</g:description>
      <g:link>https://example.com/product/12345</g:link>
      <g:image_link>https://cdn.example.com/12345.jpg</g:image_link>
      <g:additional_image_link>https://cdn.example.com/12345-2.jpg</g:additional_image_link>
      <g:availability>in_stock</g:availability>
      <g:price>29990 RUB</g:price>
      <g:sale_price>24990 RUB</g:sale_price>
      <g:brand>Samsung</g:brand>
      <g:gtin>4895183805887</g:gtin>
      <g:mpn>SM-S921BZKDSER</g:mpn>
      <g:condition>new</g:condition>
      <g:product_type>Електроніка > Смартфони</g:product_type>
      <g:google_product_category>267</g:google_product_category>
      <g:color>Чорний</g:color>
      <g:size>One Size</g:size>
      <g:item_group_id>GALAXY-S24</g:item_group_id>
      <g:shipping>
        <g:country>RU</g:country>
        <g:service>Кур'єрська доставка</g:service>
        <g:price>350 RUB</g:price>
      </g:shipping>
    </item>
  </channel>
</rss>

Атрибут item_group_id критичен для товарів з варіаціями — він групує варіанти (колір, розмір) в одну карточку у Shopping.

Google Product Category (GPC)

Google вимагає числовий код з офіційної таксономії. Для інтернет-магазину необхідна таблиця маппінгу внутрішніх категорій на GPC-коди:

class GoogleCategoryMapper
{
    private array $mapping = [
        'smartphones'      => 267,   // Electronics > Communications > Phones
        'laptops'          => 328,   // Electronics > Computers > Laptops
        'headphones'       => 232,   // Electronics > Audio > Headphones
        'shoes-men'        => 187,   // Apparel > Shoes > Men
        'refrigerators'    => 4356,  // Appliances > Kitchen Appliances > Refrigerators
    ];

    public function map(Category $category): ?int
    {
        // Пошук по slug категорії або її попередникам
        $slugs = $category->ancestors()->pluck('slug')->push($category->slug);

        foreach ($slugs->reverse() as $slug) {
            if (isset($this->mapping[$slug])) {
                return $this->mapping[$slug];
            }
        }

        return null; // Google допускає відсутність GPC, але знижує якість фіду
    }
}

Генератор фіду

class GoogleMerchantFeedBuilder
{
    public function build(string $outputPath): void
    {
        $writer = new XMLWriter();
        $writer->openUri($outputPath);
        $writer->startDocument('1.0', 'UTF-8');

        $writer->startElement('rss');
        $writer->writeAttribute('version', '2.0');
        $writer->writeAttribute('xmlns:g', 'http://base.google.com/ns/1.0');

        $writer->startElement('channel');
        $this->writeChannelMeta($writer);

        Product::with(['category.ancestors', 'brand', 'images', 'variants'])
            ->active()
            ->hasPrice()
            ->chunk(500, function ($products) use ($writer) {
                foreach ($products as $product) {
                    // Якщо у товара є варіанти — експортуємо кожний
                    if ($product->variants->isNotEmpty()) {
                        foreach ($product->variants as $variant) {
                            $this->writeVariantItem($writer, $product, $variant);
                        }
                    } else {
                        $this->writeItem($writer, $product);
                    }
                }
            });

        $writer->endElement(); // channel
        $writer->endElement(); // rss
        $writer->endDocument();
        $writer->flush();
    }

    private function writeItem(XMLWriter $w, Product $p): void
    {
        $w->startElement('item');

        $w->writeElement('g:id', $p->sku);
        $w->writeElement('g:title', $this->sanitizeTitle($p->name));
        $w->writeElement('g:description', strip_tags($p->description));
        $w->writeElement('g:link', route('product.show', $p->slug));
        $w->writeElement('g:image_link', $p->mainImage()?->url ?? '');
        $w->writeElement('g:availability', $p->in_stock ? 'in_stock' : 'out_of_stock');
        $w->writeElement('g:price', number_format($p->price, 2, '.', '') . ' RUB');

        if ($p->sale_price) {
            $w->writeElement('g:sale_price', number_format($p->sale_price, 2, '.', '') . ' RUB');
        }

        $w->endElement();
    }

    private function sanitizeTitle(string $title): string
    {
        // Google забороняє заглавні букви в заголовках цілком та спецсимволи реклами
        $title = preg_replace('/[!]{2,}/', '!', $title);
        return mb_substr($title, 0, 150);
    }
}

Завантаження через Content API v2.1

Для крупних каталогів та миттєвого оновлення ціни/остатків переважніше API:

use Google\Service\ShoppingContent;

class GoogleContentApiUploader
{
    private ShoppingContent $service;
    private string $merchantId;

    public function batchUpsert(Collection $products): void
    {
        $entries = $products->map(fn($p) => [
            'batchId'     => $p->id,
            'merchantId'  => $this->merchantId,
            'method'      => 'insert',
            'product'     => $this->toApiProduct($p),
        ])->values()->toArray();

        // Максимум 1000 товарів за запит
        foreach (array_chunk($entries, 1000) as $batch) {
            $this->service->products->custombatch([
                'entries' => $batch,
            ]);
        }
    }
}

API-інтеграція дозволяє оновлювати ціну та остаток за хвилини без очікування переобходу файлу.

Діагностика дисапрувів

Типові причини відхилення товарів:

• Missing GTIN — для брендових товарів Google вимагає GTIN; рішення: заповнити поле або виставити identifier_exists: false
• Promotional overlay on image — зображення з текстом/watermark; потрібно чисте фото товара
• Price mismatch — ціна у фіді відрізняється від ціни на сторінці; потрібна синхронізація
• Unsupported language — опис не мовою цільової країни

Логіруйте itemLevelIssues з відповіді API для автоматичного виявлення проблем:

$response = $this->service->products->get($this->merchantId, "online:ru:RU:{$sku}");
foreach ($response->getItemLevelIssues() as $issue) {
    Log::warning('GMC issue', [
        'sku'         => $sku,
        'code'        => $issue->getCode(),
        'servability' => $issue->getServability(), // 'disapproved' | 'demoted'
        'description' => $issue->getDescription(),
    ]);
}

Терміни реалізації

• Генератор XML-фіду з базовими атрибутами: 1 день
• Маппінг GPC + атрибути варіантів: +1 день
• Інтеграція Content API v2.1: +1–2 дні
• Логування дисапрувів та алерти: +0.5 дня

Типовий проект без API-інтеграції: 2 робочих дні.