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

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

סקירה כללית

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

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

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

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

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

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

שיטה: ManageLoyaltyCustomerMatch

ה-method‏ 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

ה-method‏ ManageLoyaltyCustomerMatch מחזירה אובייקט ManageLoyaltyCustomerMatchResponse:

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

שיקולים חשובים לגבי התשובות

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

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

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

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

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

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

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

הקודם
Manage loyalty programs