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

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

סקירה כללית

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

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

  • ממשק מאוחד: נקודת קצה ייחודית להוספה, לעדכון או להסרה של פרטים על רמת החברות במועדון הלקוחות.
  • עיצוב מוכוון פרטיות: כדי להגן על פרטיות המשתמשים ולמנוע בדיקות לא מורשות של החשבון, ה-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

  • ‫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:

  • כדי להקצות לקוח לסטטוס 'כסף', צריך להשתמש ב-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 Error String תיאור
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 שעשויות להצביע על חוסר התאמה בהבנת רמת השירות.

הקודם
Manage loyalty programs