Bağlılık Müşteri Eşleştirme Hizmetine Genel Bakış

Bu kılavuzda, Merchant API'de Bağlılık Programı Müşteri Eşleştirme hizmetinin nasıl kullanılacağı açıklanmaktadır. Bu hizmet, satıcıların ve satıcılar adına hareket eden üçüncü taraf bağlılık programı sağlayıcılarının, Google Arama'da organik kişiselleştirme için kullanıcı kimlikleri ve katman bilgileri gibi müşteri bağlılığı verilerini etkin bir Google Ads hesabı olmadan yönetmesine olanak tanır.

Genel Bakış

Bağlılık Programı Müşteri Eşleştirme hizmetini kullanarak bağlılık verilerini yükleyin. Bu veriler daha sonra Google Arama'da üyelere özel fiyatlandırma gibi organik bağlılık kişiselleştirme özellikleri sunmak için kullanılır. Müşterilerinizi bağlılık programı katmanlarıyla ilişkilendirmek için ManageLoyaltyCustomerMatch özel yöntemini kullanırsınız. Bu yöntem, kullanıcı kimliklerine göre bağlılık durumlarını eklemenize, güncellemenize veya kaldırmanıza olanak tanır.

Temel kavramlar

  • Birleştirilmiş arayüz: Müşteri bağlılık katmanı ayrıntılarını eklemek, güncellemek veya kaldırmak için benzersiz bir uç nokta.
  • Gizlilik öncelikli tasarım: API, kullanıcı gizliliğini korumak ve yetkisiz hesap incelemelerini önlemek için GET veya LIST işlemlerini desteklemez. Böylece veriler, alınmadan veya denetlenmeden yönetilir.
  • Esnek tanımlama: Kullanıcıları e-posta adresi, fiziksel adres veya telefon numarası gibi en az bir geçerli tanımlayıcı kullanarak eşleştirin.
  • İzne dayalı işleme: Hizmet, müşteri verilerini yalnızca son kullanıcı Google'a gerekli izni verdiğinde saklar ve kullanır. Hizmet, hesap varlığının araştırılmasını veya izin durumunu korumak ve önlemek için eşleşme yapılmazsa veya izin verilmezse sessiz bir başarı döndürür.

Ön koşullar

Bağlılık Programı Müşteri Eşleştirme Hizmeti'ni kullanmak için aşağıdaki şartlara uymanız gerekir:

  • Hesap kurulumu: Etkin bir Merchant Center hesabınızın (veya üçüncü taraf bağlılık programı sağlayıcısıysanız satıcının hesabına yetkili erişiminizin) olduğundan emin olun. Bağlılık Müşteri Eşleştirme hizmetini kullanmak için Google Ads hesabı oluşturmanız gerekmez.
  • Bağlılık programı yapılandırması: Merchant Center hesabınızda bağlılık programını etkinleştirin ve bağlılık katmanlarını tanımladığınızdan emin olun.
  • Katman sırasına dikkat edin: Bağlılık katmanlarınızın Merchant Center kullanıcı arayüzünde tanımlandığı sıraya dikkat edin. API, enum eşlemesi için tam olarak bu sırayı kullanır.

Yöntem: ManageLoyaltyCustomerMatch

ManageLoyaltyCustomerMatch yöntemi, müşteri bağlılığı ilişkilendirmelerini yönetmek için merkezi arayüz görevi görür. Hizmet, sağlanan girişe göre müşterinin bağlılık katmanı durumunun eklenip eklenmeyeceğini, güncellenip güncellenmeyeceğini veya kaldırılıp kaldırılmayacağını otomatik olarak belirler. İşlem idempotent'tır: Tekrarlanan aynı istekler, tek bir istekle aynı etkiye sahiptir.

Aşağıdaki istek, API aracılığıyla müşteri bağlılığı ilişkilendirmelerinin nasıl yönetileceğini gösterir:

POST https://merchantapi.googleapis.com/{API_VERSION}/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage

Bu istek, aşağıdaki zorunlu yol parametrelerini tanımlar:

  • API_VERSION: v1 gibi API sürümü.
  • ACCOUNT_ID: Merchant Center hesap kimliği.

İstek gövdesine bir loyaltyCustomer nesnesi ekleyin.

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

loyaltyCustomer alanları

  • userIdentifier: Müşteriyi eşleştirmek için kullanılan tanımlayıcılar kümesi. userIdentifier içinde en az bir alan sağlanmalı ve geçerli olmalıdır.
  • loyaltyTier: Müşteriyle ilişkilendirilecek bağlılık katmanı. Merchant Center kurulumundaki katman sırasıyla eşleşir. Ayrıntılı bilgi için loyaltyTier eşlemesini anlama başlıklı makaleyi inceleyin. Mevcut bir ilişkilendirmeyi kaldırmak için NON_MEMBER değerini kullanın.
  • pointBalance: Müşterinin mevcut puan bakiyesi.

userIdentifier alanları

Aşağıdaki alanlardan en az birini sağlayın:

  • emailAddress: Müşterinin e-posta adresi.
  • address: Müşterinin fiziksel adresi. PostalCode zorunludur.
  • phoneNumber: Müşterinin telefon numarası. E.164 biçimi önerilir.

loyaltyTier eşlemesini anlama

API, özel adları kullanmaz. loyaltyTier enum değerleri (TIER1 - TIER7), anlamsal etiketlerdir. Merchant Center kullanıcı arayüzünde atadığınız özel adları (ör. "Altın Ödüller") veya özel etiketleri (ör. "altın_katman") kullanmazlar. Bunun yerine, Merchant Center'daki bağlılık programı ayarlarında katmanlarınızı tanımladığınız sırayla tam olarak eşleşirler:

  • TIER1: Merchant Center bağlılık programı yapılandırmanızda listelenen ilk katmana karşılık gelir.
  • TIER2: Merchant Center bağlılık programı yapılandırmanızda listelenen ikinci katmana karşılık gelir.
  • TIER3 - TIER7: Merchant Center bağlılık programı yapılandırmanızda listelenen üçüncü ila yedinci katmanlara karşılık gelir.

Örnek:

Merchant Center bağlılık programınızda katmanlar şu sırayla tanımlanmışsa:

  1. Katman adı: "Gümüş Statüsü", katman etiketi: "gümüş"
  2. Katman adı: "Altın Üye", katman etiketi: "altın"
  3. Katman adı: "Platinum Elite", katman etiketi: "platinum"

Ardından, accounts.loyaltyCustomers.manage API çağrılarında:

  • Bir müşteriyi "Gümüş Statüsü"'ne atamak için loyaltyTier: TIER1 kullanmanız gerekir.
  • Bir müşteriyi "Altın Üye" olarak atamak için loyaltyTier: TIER2 kullanmanız gerekir.
  • Bir müşteriyi "Platinum Elite" olarak atamak için loyaltyTier: TIER3 kullanmanız gerekir.

LoyaltyTier enum değerleri

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (Müşterinin bağlılık ilişkilendirmesinin kaldırıldığını belirtmek için kullanılır)

ManageLoyaltyCustomerMatch yanıt gövdesini anlama

ManageLoyaltyCustomerMatch yöntemi bir ManageLoyaltyCustomerMatchResponse nesnesi döndürür:

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

Yanıtlarda dikkat edilmesi gerekenler

  • Başarılı upsert (veri depolandı): Bir müşterinin bağlılık katmanı ilişkilendirmesini başarıyla depolamak veya güncellemek için aşağıdaki koşulları karşılayın:

    • bir Google kullanıcısını sağlanan userIdentifier ile eşleştirirsiniz
    • İstekteki loyaltyTier değerini NON_MEMBER dışında geçerli bir değere ayarlamanız gerekir.
    • Eşleşen kullanıcı, bağlılık verilerinin kullanımına izin vermiş olmalıdır.

Yanıt, isteğinizdeki loyaltyCustomer nesnesini içerir. Bu, hizmetin verileri başarıyla işlediğini ve depoladığını gösterir:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • Başarılı silme: Müşterinin bu satıcıyla mevcut bağlılık ilişkilendirmesini başarıyla kaldırmak için aşağıdaki koşulların karşılanması gerekir:
    • bir Google kullanıcısını sağlanan userIdentifier ile eşleştirirsiniz
    • İstekteki loyaltyTier değerini NON_MEMBER olarak ayarlamanız gerekir.

Yanıt boş bir JSON nesnesi olur:

{}
  • Eşleşme yok/izin yok (sessiz başarı): Sağlanan userIdentifier bir Google Hesabı ile eşleşmiyorsa veya eşleşen kullanıcı, bağlılık verilerinin kullanımına izin vermediyse API, boş bir JSON nesnesiyle {} HTTP 200 OK durumunu döndürür. Bu durum hem ekleme/güncelleme hem de kaldırma girişimlerinde yaşanır.

Örnekler

TIER1, tanımlanan ilk katmana (ör. "Basic") karşılık gelir. TIER2, ikinci katmana (ör. "Premium") karşılık gelir.

Bir müşteriyi TIER2'ye eklemek veya e-posta adresi kullanarak durumunu güncellemek için aşağıdaki isteği gönderin:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

Kullanıcı başarıyla eşleştirildiğinde ve izin verdiğinde API aşağıdaki yanıtı döndürür:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

Eşleşme olmadığında veya kullanıcı izin vermediğinde API aşağıdaki yanıtı döndürür:

{}

Telefon numarası kullanarak bir müşterinin bağlılık ilişkilendirmesini kaldırmak için aşağıdaki isteği gönderin:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

Kayıt olup olmadığına bakılmaksızın API, aşağıdaki başarılı yanıtı döndürür:

{}

Birden fazla tanımlayıcı kullanarak müşteri eklemek veya güncellemek için aşağıdaki isteği gönderin:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

Yanıt, eşleşmeye ve rızaya bağlı olarak ilk örneğe benzer.

Hata işleme

API, standart HTTP kodlarını kullanır. Sık karşılaşılan hata dizeleri şunlardır:

HTTP kodu Hata Dizesi Açıklama
400 INVALID_ARGUMENT user_identifier veya loyalty_tier eksik ya da tanımlayıcı boş.
401 UNAUTHENTICATED Kimlik bilgileri geçersiz veya eksik.
403 PERMISSION_DENIED Kimliği doğrulanmış kullanıcının, belirtilen Merchant Center hesabına erişimi yok.
404 NOT_FOUND Belirtilen bağlılık katmanı etiketi, yapılandırmanızda mevcut değil.
412 FAILED_PRECONDITION Hesabınızda bağlılık programı yapılandırmadınız.
429 RESOURCE_EXHAUSTED Kota sınırına ulaşıldı.

Hata örnekleri

404 NOT_FOUND için örnek:

Bağlılık programı yapılandırılmamış bir hesap kimliğine gönderilen tüm geçerli istekler.

API aşağıdaki hata yanıtını döndürür:

{
  "error": {
    "code": 404,
    "message": "The loyalty program is not found for account: {ACCOUNT_ID}.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "notFound",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_ID": "{ACCOUNT_ID}",
          "REASON": "NOT_FOUND_LOYALTY_PROGRAM"
        }
      }
    ]
  }
}

Nedeni: Yoldaki satıcı hesabında etkin bir bağlılık programı yok.

400 INVALID_ARGUMENT örnekleri:

İstek, loyaltyTier alanı için geçersiz bir değer içeriyorsa hata oluşur:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER11",
    "pointBalance": 100
  }
}

API aşağıdaki hata yanıtını döndürür:

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\"",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "loyalty_customer.loyalty_tier",
            "description": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\""
          }
        ]
      }
    ]
  }
}

Nedeni: TIER11, loyaltyTier için geçerli bir enum değeri değil. Yalnızca bir katman varken TIER2'yi belirtmeye çalıştığınızda da aynı hata oluşabilir.

İstek gövdesinde zorunlu loyaltyTier alanı eksikse hata oluşur:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "pointBalance": 100
  }
}

API aşağıdaki hata yanıtını döndürür:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] Required field not provided: loyalty_customer.loyalty_tier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.loyalty_tier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

Nedeni: loyaltyTier alanı zorunludur.

Adres tanımlayıcı eksikse (ör. postalCode alanı eksikse) hata oluşur:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "address": {
        "locality": "Sunnyvale",
        "administrativeArea": "CA",
        "regionCode": "US"
      }
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API aşağıdaki hata yanıtını döndürür:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format ... Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Nedeni: Bir adres sağlanmış ancak zorunlu postalCode alanı eksik olduğundan geçerli bir tanımlayıcı olarak kabul edilmiyor.

Yapılandırılmış programın sınırları dışında bir katman dizini isterseniz hata oluşur:

Senaryo: Satıcının Merchant Center'da yapılandırılmış yalnızca bir katmanı var.

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 100
  }
}

API aşağıdaki hata yanıtını döndürür:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] The format of loyalty_customer.loyalty_tier does not match the expected format `valid LoyaltyTier`. Value: TIER2.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.loyalty_tier",
          "PATTERN": "valid LoyaltyTier",
          "FIELD_VALUE": "TIER2",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Neden: TIER2 istendi ancak hesaba bağlı bağlılık programında tanımlanmış ikinci bir katman yok.

İstek, hatalı biçimlendirilmiş bir emailAddress içeriyorsa hata oluşur:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@google"
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API aşağıdaki hata yanıtını döndürür:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format `email_address: \t \"customer@google\"\n`. Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Nedeni: E-posta adresi biçimi geçersiz.

userIdentifier nesnesi boşsa hata oluşur:

{
  "loyaltyCustomer": {
    "userIdentifier": {},
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API aşağıdaki hata yanıtını döndürür:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] Required field not provided: loyalty_customer.user_identifier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.user_identifier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

Nedeni: userIdentifier nesnesi mevcut ancak gerçek tanımlayıcı alanları içermiyor.

Not: Tanımlayıcı doğrulama.:

  • API, tanımlayıcılar üzerinde temel biçim kontrolleri gerçekleştirir (örneğin, e-posta yapısı, adreslerde postalCode bulunması).
  • Ancak ilk kontrolleri geçen bazı tanımlayıcılar herhangi bir Google kullanıcı hesabıyla eşleşmeyebilir veya arka uç eşleştirme sistemi tarafından tanınan bir biçimde olmayabilir. Bu gibi durumlarda, HTTP durumu 200 OK olan sessiz başarı boş yanıtı {} alırsınız.

En iyi uygulamalar

Entegrasyonunuzu optimize etmek için aşağıdaki en iyi uygulamaları izleyin.

  • Büyük ölçekli entegrasyon için: API, istek bazında çalıştığından büyük veri kümeleri için gerekli işleme kapasitesine ulaşmak amacıyla istemci tarafı paralelliği gerekir. Entegrasyonunuzu, aynı anda birden fazla eşzamanlı isteği yönetecek şekilde tasarlamanız gerekir. Paralelleştirme yoluyla daha yüksek hacimleri işlemek için uygulamanızı nasıl yapılandıracağınızla ilgili talimatları birden fazla istek gönderme hakkındaki kılavuzumuzda bulabilirsiniz.

  • Kota yönetimi: Varsayılan kota günde 1.000.000 istek ve dakikada 10.000 istek şeklindedir. Kotalarınızı nasıl izleyip kontrol edebileceğinizi öğrenmek için Kotalar ve sınırlar başlıklı makaleyi inceleyin.

  • E-posta adresine öncelik verin: Mümkün olduğunda müşterinin emailAddress adresini userIdentifier içine ekleyin. E-posta adresleri, kullanıcıları Google Hesaplarıyla eşleştirmek için genellikle en doğru ve güvenilir tanımlayıcıdır.

  • Boş yanıtları işleme: Uygulamanızı, boş {} yanıtlarını doğru şekilde yorumlayarak başarılı olarak değerlendirecek şekilde tasarlayın. Bu yanıtlar, gizlilik nedeniyle (eşleşme yok veya izin yok) verilerin depolanmadığı anlamına gelir. İsteği yeniden denemeyin.

  • Katman sırasını doğrulayın: API çağrılarınızda doğru TIER1 - TIER7 enum değerlerini kullandığınızdan emin olmak için Merchant Center kullanıcı arayüzünde bağlılık katmanlarınızın sırasını her zaman doğrulayın. Bu eşleme, adlarına göre değil, kullanıcı arayüzünde tanımlanan sıraya göre yapılır.

  • Hataları izleyin: API yanıtlarını günlüğe kaydedip izleyin. Entegrasyon sorunlarını yakalamak için 4xx hatalarına, özellikle de katman anlayışında bir uyuşmazlık olduğunu gösterebilecek 404 hatalarına dikkat edin.

Önceki
Manage loyalty programs