reCAPTCHA is a part of Google Cloud Fraud Defense. For more information, see Google Cloud Fraud Defense.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

במסמך הזה מוסבר איך להתקין מפתח אוניברסלי ולשלב אותו בדפי האינטרנט.

לפני שמתחילים

התקנת מפתחות אוניברסליים באתר

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

הגדרת AutoExecute (מומלץ): יירוט אוטומטי של בקשות אסינכרוניות לאחזור מהרשת לנתיבי כתובות URL שהוגדרו, וצירוף האסימון של reCAPTCHA לכותרת הבקשה.
הטמעה ידנית: משתמשת בקריאות grecaptcha.enterprise.execute() ידניות או במאפייני לחצן HTML. אתם יכולים להשתמש בשיטה הזו לבד או לצד AutoExecute בשביל בקשות לאחזור מהרשת שלא נתמכות ב-AutoExecute, בקשות שדורשות מיקום אסימון בהתאמה אישית במטען הייעודי (payload) או במהלך העברות מצטברות ל-AutoExecute.

בוחרים את האפשרות המתאימה בהתאם לגישת השילוב שלכם:

הגדרת AutoExecute

התכונה AutoExecute יכולה לפשט את השילוב של JavaScript בממשק הקצה (frontend) על ידי יירוט בקשות לאחזור מהרשת בדפי האינטרנט שלכם, וביטול קריאות ידניות ל-grecaptcha.enterprise.execute() לכל פעולה בממשק הקצה.

התכונה AutoExecute מיירטת רק בקשות אסינכרוניות לאחזור מהרשת שנוצרו באמצעות Fetch API או XMLHttpRequest, כולל בקשות ממסגרות כמו AJAX שמשתמשות בממשקי ה-API האלה.
אין תמיכה ב-AutoExecute במשאבים שנטענים באופן אוטומטי בזמן הטעינה של הדף. במקום זאת, צריך להחיל את AutoExecute על בקשות לאחזור מהרשת שמופעלות על ידי פעולות של המשתמשים בדף, כמו לחיצה על כפתור התחברות.
כדי למנוע מצב שבו אימותים של Fraud Defense יגרמו לזמן קצוב לתפוגה ברשת, צריך להחיל את הזמן הקצוב לתפוגה ישירות על הבקשות. משתמשים ב-AbortSignal.timeout(n) ל-Fetch API ובמאפיין XMLHttpRequest.timeout ל-XMLHttpRequest.

הוספת תג הסקריפט לדפי האינטרנט

כדי לטעון את Fraud Defense בדף האינטרנט, מוסיפים את JavaScript API עם המפתח האוניברסלי בתוך הרכיב <head></head> של דף האינטרנט:

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

כברירת מחדל, Fraud Defense משתמש בשפת הדפדפן. אם רוצים לציין שפה אחרת, משתמשים במאפיין hl=LANG בסקריפט. לדוגמה, כדי להשתמש בצרפתית, מציינים את הפרטים הבאים:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

כאן מפורטות השפות שנתמכות ב-Fraud Defense.

הגדרת נקודות קצה מוגנות

הסקריפט של Fraud Defense משתלב באופן אוטומטי עם פעולות הרשת שמוגדרות במדיניות של המפתח האוניברסלי. בקטע הזה מוגדר מיפוי של נתיבי כתובות ה-URL‏ (path) לשמות של פעולות (action).

אם הסקריפט של Fraud Defense מזהה בקשה אסינכרונית לאחזור מהרשת לנתיב ממופה, הוא מיירט את הבקשה, מפעיל הערכת סיכונים ויכול להיות שיציג למשתמש אתגר CAPTCHA לפני שהבקשה המקורית תמשיך. האסימון שנוצר בתגובה מצורף באופן אוטומטי לכותרת X-Recaptcha-Token בבקשה.

gcloud

כדי לבדוק את הגדרת המדיניות הנוכחית של המפתח האוניברסלי, משתמשים בפקודה gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

כדי לעדכן את הגדרת המדיניות עם נקודות הקצה המוגנות, יוצרים קובץ YAML (לדוגמה, POLICY.yaml) שמגדיר את הנתיבים והפעולות המוגנים:

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

מעדכנים את הגדרת המפתח באמצעות קובץ ה-YAML, בעזרת הפקודה gcloud alpha recaptcha policies update:

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

‫API בארכיטקטורת REST

כדי לעדכן את הגדרת המדיניות ולהגדיר נקודות קצה מוגנות באמצעות ה-API בארכיטקטורת REST, משתמשים ב-method‏ projects.keys.updatePolicy.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
‫KEY_ID: המזהה של המפתח האוניברסלי

ה-method של ה-HTTP וכתובת ה-URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup

תוכן בקשת JSON:

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

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

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup" | Select-Object -Expand Content

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

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

‫action: שם הפעולה חייב להכיל בין תו אחד ל-100 תווים, ורק אותיות, מספרים, קווים נטויים (/) וקווים תחתונים (_).
‫path (תלוי אותיות רישיות): הנתיב חייב לעמוד בקריטריונים הבאים:
- להיות ייחודי, להתחיל ב-/ ולהכיל בין תו אחד ל-200 תווים בלי קווים נטויים עוקבים (//).
- לכלול לפחות פלח אחד שהוא לא תו כללי לחיפוש (לדוגמה, אי אפשר להשתמש ב-/, /*, /** או /*/).
- תווים כלליים לחיפוש חייבים לתפוס מקטעים שלמים: * תואם למקטע בודד (לדוגמה, /api/*/login או /api/* תקינים, אבל /api/login* לא תקין), ו-** תואם למספר מקטעים בתור המקטע האחרון בלבד (לדוגמה, /api/** תקין, אבל /api/**/login לא תקין).

בקשות של צד שלישי: אם כלים של צד שלישי שפועלים בדף (כמו סקריפטים של ניתוח נתונים או של שותפים) שולחים בקשות לנתיבים שתואמים לנקודות הקצה המוגנות (לדוגמה, https://analytics.example.net/login שתואם ל-/login), AutoExecute יירט גם אותן. זה יכול לגרום לזמן אחזור נוסף ברשת, למדדים מוטים או לאתגרי CAPTCHA לא צפויים. כדי למנוע התנגשויות, ודאו שהנתיבים המוגנים ייחודיים (לדוגמה, /auth/v1/login), או השתמשו בהתקנה ידנית אם יש התנגשויות בנתיבים.
ממשקי API חוצי-דומיינים: אם ה-API לקצה העורפי מתארח בדומיין שונה מהאתר (לדוגמה, examplecdn.net לעומת www.example.com), AutoExecute פועל באופן אוטומטי בלי הגדרת דומיין נוספת.

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

ב-backend, מקבלים את אסימון התגובה מהכותרת של בקשת X-Recaptcha-Token ויוצרים הערכה תוך שתי דקות.

התקנה ידנית

מומלץ להוסיף אימות של Fraud Defense לאינטראקציה של משתמש שצריך לאמת. לדוגמה, אם רוצים לאמת את פעולת השליחה של טופס, צריך להוסיף אימות של Fraud Defense לפעולת השליחה.

בהתאם למקום שבו רוצים להוסיף את האימות של Fraud Defense, בוחרים באפשרות המתאימה:

הוספת אימות לאינטראקציה של משתמש
הוספת Fraud Defense ללחצן HTML

הוספת אימות באינטראקציה של המשתמש

כדי לטעון את reCAPTCHA בדף האינטרנט, מוסיפים את JavaScript API עם המפתח האוניברסלי בתוך הרכיב <head></head> של דף האינטרנט:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
כברירת מחדל, Fraud Defense משתמש בשפת הדפדפן. אם רוצים לציין שפה אחרת, משתמשים במאפיין hl=LANG בסקריפט. לדוגמה, כדי להשתמש בצרפתית, מציינים את הפרטים הבאים:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

כאן מפורטות השפות הנתמכות.

אם רוצים לציין מיקום לתג, משתמשים ב-badge=LOCATION כפרמטר של שאילתה בתג הסקריפט. לדוגמה, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. כברירת מחדל, המיקום מוגדר כ-bottomright. ערכים אפשריים אחרים הם inline ו-bottomleft.
כדי להוסיף אימות של Fraud Defense לאינטראקציה של משתמש:
1. כדי לוודא שהפונקציה grecaptcha.enterprise.execute() תפעל אחרי שספריית Fraud Defense תיטען, צריך להשתמש ב-grecaptcha.enterprise.ready().
2. מפעילים את grecaptcha.enterprise.execute() בכל אינטראקציה שרוצים להגן עליה באמצעות המפתח האוניברסלי. בפרמטר action, מציינים שם משמעותי לאינטראקציה של המשתמש. מידע נוסף על פעולות
  
  טיפ: כדאי להוסיף את הקריאה ל-execute לפעולות רגישות כמו LOGIN,‏ SIGNUP,‏ PASSWORD_RESET או PURCHASE.
  
  בדוגמה הבאה אפשר לראות איך להפעיל את grecaptcha.enterprise.execute() בפעולת התחברות:
```
<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>
```
אחרי שנוצר הטוקן, שולחים את הטוקן של reCAPTCHA לקצה העורפי ויוצרים בדיקה תוך שתי דקות.

חשוב: בקצה העורפי צריך לציין את assessment.event.expected_action (או expectedAction ב-JSON) ב-CreateAssessmentRequest, והוא צריך להתאים לפעולה שהוגדרה בקריאה ל-execute(). לדוגמה, אם מגדירים את הפעולה בקצה הקדמי כ-LOGIN, צריך להגדיר את expected_action כ-LOGIN בקצה העורפי כשיוצרים הערכה לבקשה הזו. אם אין התאמה, זה מצביע על כך שתוקף מנסה לזייף פעולות.

הוספת Fraud Defense ללחצן HTML

כדי לטעון את reCAPTCHA בדף האינטרנט, מוסיפים את ה-API של JavaScript עם המפתח האוניברסלי בתוך הרכיב <head></head> של דף האינטרנט:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
כברירת מחדל, Fraud Defense משתמש בשפת הדפדפן. אם רוצים לציין שפה אחרת, משתמשים במאפיין hl=LANG בסקריפט. לדוגמה, כדי להשתמש בצרפתית, מציינים את הפרטים הבאים:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

כאן מפורטות השפות שנתמכות ב-Fraud Defense.
כדי להוסיף את Fraud Defense ללחצן HTML:
1. מגדירים פונקציית קריאה חוזרת (callback) כדי לטפל בטוקן.
```
<script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>
```
מידע נוסף זמין במאמר בנושא השיטה requestSubmit()‎.
1. מוסיפים מאפיינים ללחצן ה-HTML.
```
<button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>
```
אם רוצים לציין מיקום לתג, משתמשים במאפיין data-badge="LOCATION" ברכיב שכולל את class="g-recaptcha". כברירת מחדל, המיקום מוגדר ל-bottomright. ערכים אפשריים אחרים הם inline ו-bottomleft.
1. כשמשתמשים בלחצן הזה כדי לשלוח טופס באתר, פרמטר ה-POST מסוג g-recaptcha-response מכיל את אסימון התגובה.
הערה: אם מגדירים את הכפתור g-recaptcha כ-disabled, הכפתור מופעל כשטוענים את Fraud Defense.
אחרי שנוצר הטוקן, שולחים את הטוקן של reCAPTCHA לקצה העורפי ויוצרים בדיקה תוך שתי דקות.

חשוב: ה-backend צריך לציין את הערך assessment.event.expected_action (או expectedAction ב-JSON) ב-CreateAssessmentRequest, והוא צריך להתאים לפעולה שהוגדרה בכפתור. לדוגמה, אם מגדירים את פעולת הכפתור כ-submit, ה-backend צריך להגדיר את expected_action כ-submit כשיוצרים הערכה לבקשה הזו. אם אין התאמה, זה מצביע על כך שתוקף מנסה לזייף פעולות.

המאמרים הבאים

כדי להפעיל אתגרי CAPTCHA על סמך כללים בהתאמה אישית, מגדירים כללי מדיניות לאתגרים.
כדי להעריך את אסימון התגובה של reCAPTCHA, יוצרים הערכה.