סקירה כללית של שירות ההתאמה ללקוחות של מועדון הלקוחות

במדריך הזה מוסבר איך להשתמש בשירות התאמה ללקוחות נאמנות ב-Merchant API. השירות הזה מאפשר למוֹכרים לנהל נתונים של מועדון לקוחות, כמו מזהי משתמשים ומידע על רמת החברות, כדי לבצע התאמה אישית אורגנית בחיפוש Google, בלי שיהיה להם חשבון פעיל ב-Google Ads.

סקירה כללית

אתם יכולים להשתמש בשירות 'התאמה ללקוחות ממועדון הלקוחות' כדי להעלות נתונים של מועדון הלקוחות, שמשמשים לאחר מכן להצגת תכונות להתאמה אישית אורגנית של מועדון הלקוחות בחיפוש Google, כמו הצגת מחירים ספציפיים לחברי מועדון. אתם משתמשים בשיטה ManageLoyaltyCustomerMatch custom כדי לשייך את הלקוחות שלכם לרמות במועדון הלקוחות, וכך להוסיף, לעדכן או להסיר את סטטוס החברות שלהם במועדון על סמך מזהי המשתמשים.

מושגים מרכזיים

  • ממשק מאוחד: נקודת קצה ייחודית להוספה, לעדכון או להסרה של פרטי רמת נאמנות של לקוחות.
  • עיצוב מוכוון פרטיות: כדי להגן על פרטיות המשתמשים ולמנוע בדיקות לא מורשות של חשבונות, ה-API לא תומך בפעולות GET או LIST, וכך הנתונים מנוהלים בלי שאפשר לאחזר אותם או לבדוק אותם.
  • זיהוי גמיש: התאמת משתמשים באמצעות מזהה תקף אחד לפחות, כמו כתובת אימייל, כתובת פיזית או מספר טלפון.
  • עיבוד שמבוסס על הסכמה: השירות מאחסן ומשתמש בנתוני לקוחות רק אם משתמש הקצה נתן את ההסכמה הנדרשת ל-Google. כדי להגן על החשבון ולמנוע בדיקות של קיום החשבון או סטטוס ההסכמה, השירות מחזיר הצלחה שקטה אם לא נמצאה התאמה או אם לא ניתנה הסכמה.

דרישות מוקדמות

כדי להשתמש בשירות 'התאמה ללקוחות ממועדון הלקוחות', צריך לעמוד בדרישות הבאות:

  • הגדרת החשבון: מוודאים שיש לכם חשבון פעיל ב-Merchant Center. לא צריך ליצור חשבון Google Ads כדי להשתמש בשירות התאמה ללקוחות ממועדון הלקוחות.
  • הגדרת מועדון הלקוחות: מפעילים את מועדון הלקוחות בחשבון Merchant Center ומוודאים שהגדרתם רמות חברות במועדון.
  • סדר השלבים: חשוב לשים לב לסדר שבו מוגדרים השלבים במועדון הלקוחות בממשק המשתמש של Merchant Center. ה-API משתמש ברצף הזה בדיוק למיפוי של סוגי הנתונים המנויים.

שיטה: ManageLoyaltyCustomerMatch

השיטה ManageLoyaltyCustomerMatch משמשת כממשק מרכזי לניהול שיוכים של לקוחות למועדוני לקוחות. על סמך הקלט שסופק, השירות קובע באופן אוטומטי אם להוסיף, לעדכן או להסיר את סטטוס רמת המועדון של הלקוח. הפעולה היא אידמפוטנטית: לבקשות חוזרות זהות יש את אותה השפעה כמו לבקשה יחידה.

בדוגמה הבאה מוצגת בקשה לניהול שיוכים של מועדוני לקוחות באמצעות ה-API:

POST https://merchantapi.googleapis.com/{api_version}/accounts/{account_id}/loyaltyCustomers:manage

הבקשה הזו מגדירה את הפרמטרים הנדרשים הבאים של הנתיב:

  • ‫api_version: גרסת ה-API, למשל v1.
  • ‫account_id: מספר חשבון Merchant Center.

כוללים אובייקט loyaltyCustomer בגוף הבקשה.

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

loyaltyCustomer fields

  • ‫userIdentifier: קבוצת המזהים שמשמשת להתאמה ללקוח. צריך לספק לפחות שדה אחד ב-userIdentifier, והוא צריך להיות תקין.
  • ‫loyaltyTier: רמת הנאמנות לשיוך ללקוח. ממופה לסדר של רמת המחיר בהגדרה של Merchant Center. פרטים נוספים זמינים במאמר בנושא הסבר על מיפוי loyaltyTier. כדי להסיר שיוך קיים, משתמשים בערך NON_MEMBER.
  • ‫pointBalance: יתרת הנקודות הנוכחית של הלקוח.

שדות userIdentifier

צריך לספק לפחות אחד מהפרטים של השדות הבאים:

  • ‫emailAddress: כתובת האימייל של הלקוח.
  • ‫address: הכתובת הפיזית של הלקוח. חובה לציין מיקוד.
  • ‫phoneNumber: מספר הטלפון של הלקוח. מומלץ להשתמש בפורמט E.164.

הסבר על מיפוי loyaltyTier

ה-API לא משתמש בשמות המותאמים אישית. ערכי ה-enum‏ loyaltyTier (מ-TIER1 עד TIER7) הם תוויות סמנטיות. הם לא משתמשים בשמות המותאמים אישית (לדוגמה, Gold Rewards) או בתוויות המותאמות אישית (לדוגמה, gold_tier) שהקציתם בממשק המשתמש של Merchant Center. במקום זאת, הן ממופות באופן מדויק לסדר שבו הגדרתם את הרמות בהגדרות של מועדון הלקוחות ב-Merchant Center:

  • ‫TIER1: תואם לרמה הראשונה שמופיעה בהגדרות של מועדון הלקוחות ב-Merchant Center.
  • ‫TIER2: תואם לרמה השנייה שמופיעה בהגדרות של מועדון הלקוחות ב-Merchant Center.
  • ‫TIER3 עד TIER7: תואם לרמות השלישית עד השביעית שמופיעות בהגדרות של מועדון הלקוחות ב-Merchant Center.

דוגמה:

אם במועדון הלקוחות שלכם ב-Merchant Center מוגדרות רמות בסדר הזה:

  1. שם הרמה: Silver Status, תווית הרמה: silver
  2. שם הרמה: Gold Member, תווית הרמה: gold
  3. שם הרמה: Platinum Elite, תווית הרמה: platinum

אחר כך, בקריאות ל-API של accounts.loyaltyCustomers.manage:

  • כדי להקצות לקוח לסטטוס Silver, צריך להשתמש ב-loyaltyTier: TIER1.
  • כדי להקצות לקוח ל"חבר מועדון זהב", צריך להשתמש ב-loyaltyTier: TIER2.
  • כדי להקצות לקוח לסטטוס Platinum Elite, צריך להשתמש ב-loyaltyTier: TIER3.

ערכי enum של LoyaltyTier

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (משמש לסימון הסרה של השיוך של הלקוח למועדון הלקוחות)

הסבר על גוף התגובה של ManageLoyaltyCustomerMatch

השיטה ManageLoyaltyCustomerMatch מחזירה אובייקט ManageLoyaltyCustomerMatchResponse:

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

שיקולים חשובים לגבי תשובות אפשריות:

  • הוספה או עדכון מוצלחים (נתונים שנשמרו): כדי לשמור או לעדכן בהצלחה את השיוך של לקוח למועדון, צריך לעמוד בתנאים הבאים:

    • התאמה למשתמש ב-Google עם הערך userIdentifier שסופק
    • הגדרתם את הערך loyaltyTier בבקשה לערך תקין שאינו NON_MEMBER
    • המשתמש התואם הסכים לשימוש בנתוני מועדון הלקוחות

התגובה מכילה את אובייקט loyaltyCustomer מהבקשה, שמציין שהנתונים עברו עיבוד ונשמרו בהצלחה:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • מחיקה מוצלחת: כדי להסיר בהצלחה את השיוך הקיים של מועדון הלקוחות של הלקוח למוכר הזה, צריך לוודא שהתנאים הבאים מתקיימים:
    • התאמה למשתמש ב-Google עם הערך userIdentifier שסופק
    • הגדרתם את loyaltyTier בבקשה ל-NON_MEMBER

התגובה היא אובייקט JSON ריק:

{}
  • אין התאמה / אין הסכמה (הצלחה שקטה): אם הערך של userIdentifier לא תואם לחשבון Google, או אם המשתמש התואם לא הסכים לשימוש בנתוני מועדון הלקוחות, ה-API מחזיר סטטוס HTTP 200 OK עם אובייקט JSON ריק: {}. הדבר קורה גם בניסיונות של upsert וגם בניסיונות של הסרה.

דוגמאות

‫TIER1 מתאים לרמה הראשונה שהוגדרה למוֹכר, זו שנקראת Basic, ו-TIER2 מתאים לרמה השנייה – Premium

כדי להוסיף לקוח ל-TIER2 או לעדכן את הסטטוס שלו באמצעות כתובת אימייל, שולחים את הבקשה הבאה:

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

אם המשתמש זוהה בהצלחה והביע הסכמה, ה-API מחזיר את התגובה הבאה:

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

אם אין התאמה או שהמשתמש לא הביע הסכמה, ה-API מחזיר את התגובה הבאה:

{}

כדי להסיר את השיוך של לקוח למועדון באמצעות מספר טלפון, שולחים את הבקשה הבאה:

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

גם אם רשומה קיימת וגם אם לא, ה-API מחזיר את תגובת ההצלחה הבאה:

{}

כדי להוסיף או לעדכן לקוח באמצעות כמה מזהים, שולחים את הבקשה הבאה:

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

התגובה דומה לדוגמה הראשונה, בהתאם להתאמה ולהסכמה.

טיפול בשגיאות

ה-API משתמש בקודים סטנדרטיים של HTTP. מחרוזות שגיאה נפוצות:

קוד HTTP מחרוזת שגיאה תיאור
400 INVALID_ARGUMENT חסר user_identifier או loyalty_tier, או שהמזהה ריק.
401 UNAUTHENTICATED פרטי כניסה חסרים או לא תקינים.
403 PERMISSION_DENIED למשתמש המאומת אין גישה לחשבון Merchant Center שצוין.
404 NOT_FOUND תווית הרמה במועדון הלקוחות שצוינה לא קיימת בהגדרות שלכם.
412 FAILED_PRECONDITION לא הגדרתם מועדון לקוחות בחשבון.
429 RESOURCE_EXHAUSTED הגעת למכסה המקסימלית.

דוגמאות לשגיאות

דוגמה ל-404 NOT_FOUND:

כל בקשה תקינה למספר חשבון שלא הוגדר בו מועדון לקוחות.

ה-API מחזיר את תגובת השגיאה הבאה:

{
  "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"
        }
      }
    ]
  }
}

הסיבה: בחשבון של המוכר/ת בנתיב אין מועדון לקוחות פעיל.

דוגמאות ל-400 INVALID_ARGUMENT:

שגיאה מתרחשת אם הבקשה מכילה ערך לא תקין בשדה loyaltyTier:

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

ה-API מחזיר את תגובת השגיאה הבאה:

{
  "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\""
          }
        ]
      }
    ]
  }
}

הסיבה: הערך TIER11 הוא לא ערך enum תקין עבור loyaltyTier. אותה שגיאה יכולה להתרחש כשמנסים לציין TIER2 כשזמינה רק רמה אחת.

אם שדה החובה loyaltyTier חסר בגוף הבקשה, מתרחשת שגיאה:

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

ה-API מחזיר את תגובת השגיאה הבאה:

{
  "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"
        }
      }
    ]
  }
}

סיבה: השדה loyaltyTier הוא חובה.

שגיאה מתרחשת אם מזהה הכתובת לא שלם, למשל אם השדה postalCode חסר:

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

ה-API מחזיר את תגובת השגיאה הבאה:

{
  "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"
        }
      }
    ]
  }
}

הסיבה: צוינה כתובת, אבל חסר בה השדה postalCode הנדרש, ולכן היא לא נחשבת למזהה תקין.

אם מבקשים אינדקס של רמת חברות שחורג מהגבולות של התוכנית שהוגדרה, תופיע שגיאה:

תרחיש: למוֹכר יש רק רמת חברות אחת שהוגדרה ב-Merchant Center.

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

ה-API מחזיר את תגובת השגיאה הבאה:

{
  "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"
        }
      }
    ]
  }
}

הסיבה: נשלחה בקשה ל-TIER2, אבל במועדון הלקוחות שמקושר לחשבון לא מוגדרת רמה שנייה.

אם הבקשה מכילה emailAddress עם מבנה שגוי, מתרחשת שגיאה:

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

ה-API מחזיר את תגובת השגיאה הבאה:

{
  "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"
        }
      }
    ]
  }
}

הסיבה: הפורמט של כתובת האימייל לא תקין.

שגיאה מתרחשת אם האובייקט userIdentifier ריק:

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

ה-API מחזיר את תגובת השגיאה הבאה:

{
  "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"
        }
      }
    ]
  }
}

הסיבה: האובייקט userIdentifier קיים אבל לא מכיל שדות מזהים בפועל.

הערה לגבי אימות מזהים:

  • ה-API מבצע בדיקות בסיסיות של הפורמט של המזהים (לדוגמה, מבנה אימייל, נוכחות של postalCode בכתובות).
  • עם זאת, יכול להיות שחלק מהמזהים שעוברים את הבדיקות הראשוניות לא תואמים לאף חשבון משתמש ב-Google, או שהם לא בפורמט שמערכת ההתאמה בעורף המערכת מזהה. במקרים כאלה, תקבלו תגובה ריקה של הצלחה שקטה {} עם סטטוס HTTP 200 OK.

שיטות מומלצות

כדי לבצע אופטימיזציה של השילוב, מומלץ לפעול לפי השיטות המומלצות הבאות.

  • לשילוב בקנה מידה גדול: מכיוון שה-API פועל על בסיס כל בקשה, נדרשת מקביליות בצד הלקוח כדי להשיג את התפוקה הנדרשת עבור מערכי נתונים גדולים. מומלץ לתכנן את השילוב כך שיוכל לנהל כמה בקשות בו-זמניות. כדי לקבל הנחיות לגבי מבנה ההטמעה שיאפשר לכם לטפל בנפחים גדולים יותר באמצעות מקביליות, אפשר לעיין במדריך שלנו בנושא איך לשלוח כמה בקשות.

  • ניהול מכסות: מכסת ברירת המחדל היא 1,000,000 בקשות ביום ו-10,000 בקשות בדקה. במאמר מכסות ומגבלות מוסבר איך אפשר לעקוב אחרי המכסות ולבדוק אותן.

  • תעדוף כתובת אימייל: כשזה אפשרי, כדאי לכלול את emailAddress של הלקוח ב-userIdentifier. כתובות אימייל הן בדרך כלל המזהה המדויק והמהימן ביותר להתאמת משתמשים לחשבונות Google שלהם.

  • טיפול בתשובות ריקות: צריך לתכנן את האפליקציה כך שתפרש נכון תשובות ריקות של {} כהצלחה, ותבין שהמשמעות היא שהנתונים לא נשמרו מסיבות שקשורות לפרטיות (אין התאמה או אין הסכמה). אל תנסו לשלוח את הבקשה שוב.

  • בדיקת סדר הרמות: חשוב תמיד לבדוק את סדר רמות המועדון בממשק המשתמש של Merchant Center כדי לוודא שאתם משתמשים בערכי ה-enum הנכונים TIER1 עד TIER7 בקריאות ה-API. המיפוי הזה מבוסס על הסדר שמוגדר בממשק המשתמש, ולא על השמות שלהם.

  • מעקב אחר שגיאות: כדאי לרשום ביומן ולעקוב אחרי תגובות API, ולשים לב לשגיאות 4xx כדי לזהות בעיות בשילוב, במיוחד שגיאות 404 שעשויות להצביע על חוסר התאמה בהבנת רמת השירות.