Google AI Shopping Guide

Overview

Google's Universal Commerce Protocol (UCP) enables Google AI assistants to discover your products, help customers find what they need, and facilitate purchases. This guide covers setting up UCP integration with ZaLink.

Prerequisites

• A ZaLink account with an active subscription (Connect or Manage tier)
• Your store connected to ZaLink (Zid, Salla, Shopify, or WooCommerce)
• Products synced to your ZaLink catalog
• A Google Cloud Platform account (for advanced features)

Features by Tier

UCP features available depend on your subscription tier:

Step 1: Enable Google AI Connection

Navigate to Dashboard > AI Connections > Google and toggle "Enable Google AI Shopping". This activates the UCP endpoints for your store.

Step 2: Configure Discovery Settings

Set up how Google discovers your store and products:

• Store Discovery: Enable your store to be found by Google agents
• Product Discovery: Configure product feed settings
• Category Mapping: Map your categories to Google's taxonomy

Step 3: Agent Management

Control which Google agents can access your store:

• Approved Agents: Whitelist specific Google agents
• Access Levels: Set read/write permissions per agent
• Rate Limits: Configure request limits per agent

Step 4: Identity Linking

Enable customer identity linking for personalized experiences:

• Google Account Linking: Allow customers to link their Google account
• Order History: Enable order history access for reorders
• Preferences: Sync customer preferences across platforms

Step 5: OAuth Configuration

Set up OAuth 2.0 for secure agent authentication:

• Client ID: Your store's OAuth client identifier
• Client Secret: Securely stored authentication secret
• Redirect URIs: Authorized callback URLs
• Scopes: Define permission scopes for agents

Webhook Signature Verification

UCP uses ES256 (ECDSA with SHA-256) for webhook signature verification. Here's how to verify signatures:

// ES256 Webhook Signature Verification (Node.js)
import crypto from 'crypto';

function verifyUCPWebhook(payload: string, signature: string, publicKeyJWK: object): boolean {
  // Convert JWK to PEM format
  const publicKey = crypto.createPublicKey({ key: publicKeyJWK, format: 'jwk' });

  // Decode base64url signature
  const signatureBuffer = Buffer.from(signature.replace(/-/g, '+').replace(/_/g, '/'), 'base64');

  // Verify with ES256 (SHA-256)
  const verify = crypto.createVerify('SHA256');
  verify.update(payload);
  verify.end();

  return verify.verify(publicKey, signatureBuffer);
}

// Usage in Express handler:
app.post('/webhooks/ucp', async (req, res) => {
  const signature = req.headers['x-ucp-signature'] as string;
  const payload = JSON.stringify(req.body);

  // Fetch merchant's public key from /.well-known/ucp
  const publicKey = await fetchMerchantPublicKey(req.body.merchant_id);

  if (!verifyUCPWebhook(payload, signature, publicKey)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process verified webhook...
});

Testing Your Integration

Verify your UCP integration is working:

1. Use Google's UCP testing tool to validate endpoints
2. Test product discovery with sample queries
3. Verify checkout flow with test orders
4. Check webhook delivery for order events

API Reference

For developers building custom integrations, see the UCP API documentation for discovery endpoints, OAuth setup, and event webhooks.

Troubleshooting

• Discovery failing: Verify your store's UCP manifest is accessible
• OAuth errors: Check client credentials and redirect URIs
• Missing products: Ensure products meet Google's requirements
• Agent access denied: Review agent whitelist settings