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

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

הטמעה של מפתחות אוניברסליים באתר

כדי להתקין את המפתח האוניברסלי ולעזור בהגנה על דפי האינטרנט, אפשר לבחור באפשרות ההגדרה של Google Cloud Fraud Defense AutoExecute או בהתקנה הרגילה של JavaScript:

הגדרת הפעלה אוטומטית

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

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

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

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

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

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

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

הפרמטר path תומך בתבניות glob עם הכללים הבאים:

חייב להתחיל ב-/ ולא יכול להיות ריק.
לא יכול להיות /* או /** עצמאי, כי הפעלת ההגנה מפני הונאות בכל בקשה לשרת העורפי עלולה לפגוע בביצועים.
תווים כלליים * (התאמה לפלח נתיב יחיד) ו-** (התאמה לכמה פלחי נתיב) צריכים לתפוס את כל פלח הנתיב (לדוגמה, /api/*/login או /api/* הם תקינים, /api/login* לא תקין).
תו ה-wildcard ‏** חייב להיות רק בחלק האחרון של הנתיב (לדוגמה, /api/** הוא תקין, /api/**/login הוא לא תקין).

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

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

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

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

במאמר קודי שפות ל-Fraud Defense מפורטות השפות הנתמכות.

אם רוצים לציין מיקום לתג, משתמשים ב-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>
```
  s
אחרי שהטוקן נוצר, שולחים את טוקן reCAPTCHA אל ה-backend ויוצרים מבדק תוך שתי דקות.

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

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

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

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

במאמר קודי שפות ל-Fraud Defense מפורטות השפות הנתמכות.
כדי להוסיף את התכונה 'Fraud Defense' לכפתור HTML, מבצעים את הפעולות הבאות:
1. מגדירים פונקציית קריאה חוזרת לטיפול באסימון.
```
<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, הלחצן מופעל כשהכלי 'הגנה מפני הונאות' נטען.
אחרי שהטוקן נוצר, שולחים את טוקן reCAPTCHA אל ה-backend ויוצרים מבדק תוך שתי דקות.

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

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

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