הרשאות

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

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

ההרשאות הזמינות

הפעולה יכולה לבקש את ההרשאות הבאות:

  • DEVICE_PRECISE_LOCATION: מבקשת את המיקום המדויק של המכשיר של המשתמש (קואורדינטות וכתובת פיזית).
  • DEVICE_COARSE_LOCATION: מבקשת את מיקום המכשיר המשוער של המשתמש (מיקוד ועיר).

הגדרת ההרשאות

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

הוספת סוג של משבצת הרשאה

אפשר להעניק לפעולה את היכולת לקבל פרטי משתמש באמצעות סוג משבצת actions.type.Permission.

כדי להגדיר את סוג יחידת ה-Slot, פועלים לפי השלבים הבאים:

  1. עוברים אל Actions Console ובוחרים או יוצרים פרויקט.
  2. בתפריט העליון לוחצים על פיתוח.
  3. בקטע סצנות, לוחצים על הסצנה שאליה רוצים להוסיף את תהליך ההרשאה.
  4. בקטע מילוי משבצת בסצנה, לוחצים על + כדי להוסיף מיקום חדש.

  5. בתפריט הנפתח בחירת סוג, בוחרים את סוג מיקום המודעה actions.type.Permission.

  6. בשדה שם המשבצת מזינים שם למשבצת הזאת.

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

הגדרת יחידת קיבולת (Slot)

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

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

בקטע הקוד הבא מוצגת דוגמה להגדרה של משבצת זמן:

{
  "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValueSpec",
  "context": "Context string",
  "permissions": ["DEVICE_PRECISE_LOCATION"]
}

ההודעה שתוצג למשתמשים תהיה בצורת "$context_string, צריך רק לקבל את המיקום הנוכחי שלך מ-Google. זה בסדר?"

אתם יכולים לקבל את פרטי המשתמש הבאים באמצעות קודי ההרשאות:

הרשאה תיאור
DEVICE_PRECISE_LOCATION מיקום מדויק של המכשיר (קואורדינטות וכתובת רחוב)
DEVICE_COARSE_LOCATION מיקום משוער של המכשיר (מיקוד ועיר)

קבלת תוצאת ההרשאה

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

בדיקת סטטוס ההרשאה

כשהמשתמש מעניק הרשאה, הסטטוס שמתקבל נכתב בסשן. המשויך לחריץ.

אפשר לבדוק את סטטוס ההרשאה על ידי בדיקת הערך של session.params.<slot_name>.permissionStatus במצב של סצנה.

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

  1. עוברים אל Actions Console ולוחצים על פיתוח בתפריט העליון.
  2. בקטע סצנות, לוחצים על הסצנה שמכילה את משבצת ההרשאה.
  3. בקטע תנאי של הסצנה, לוחצים על + כדי להוסיף סצנה חדשה. תנאי.

  4. מזינים את התנאי הבא כדי לבדוק את סטטוס ההרשאה (כאשר &lt;slot_name&gt; הוא השם של פרמטר הסשן שהגדרתם משבצת):

    scene.slots.status == "FINAL" && (session.params.<slot_name>.permissionStatus == "PERMISSION_GRANTED" || session.params.<slot_name>.permissionStatus == "ALREADY_GRANTED")

  5. בקטע תנאי של הסצנה, לוחצים על + כדי להוסיף סצנה חדשה. תנאי.

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

    scene.slots.status == "FINAL"

  7. בקטע תנאי של הסצנה, לוחצים על + כדי להוסיף סצנה חדשה. תנאי.

  8. כדי לטפל בפנייה שבה המשתמש כבר שלח, צריך להזין את התנאי הבא. מורשה, ואין צורך לבקש אותו שוב:

    "DEVICE_PRECISE_LOCATION" in user.permissions

קריאת פרטי משתמשים

אם המשתמש מעניק הרשאה, פרטי המשתמש יסופקו את הבקשות הבאות.

בקטע הקוד שלמטה אפשר לראות מידע על מיקום המכשירים כלולה בבקשה ל-webhook בקטע device.currentLocation:

בקשת JSON 
  {
      "handler": {
        "name": "handler"
      },
      "intent": {
        "name": "",
        "params": {
          "deviceLoc": {
            "original": "",
            "resolved": {
              "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue",
              "permissionStatus": "PERMISSION_GRANTED",
              "grantedPermissions": [
                "DEVICE_PRECISE_LOCATION"
              ]
            }
          }
        },
        "query": "Yes"
      },
      "scene": {
        "name": "Scene",
        "slotFillingStatus": "FINAL",
        "slots": {
          "deviceLoc": {
            "mode": "REQUIRED",
            "status": "SLOT_UNSPECIFIED",
            "value": {
              "grantedPermissions": [
                "DEVICE_PRECISE_LOCATION"
              ],
              "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue",
              "permissionStatus": "PERMISSION_GRANTED"
            },
            "updated": true
          }
        },
        "next": {
          "name": "actions.scene.END_CONVERSATION"
        }
      },
      "session": {
        "id": "session_id",
        "params": {
          "deviceLoc": {
            "grantedPermissions": [
              "DEVICE_PRECISE_LOCATION"
            ],
            "permissionStatus": "PERMISSION_GRANTED",
            "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue"
          }
        },
        "typeOverrides": [],
        "languageCode": ""
      },
      "user": {
        "locale": "en-US",
        "params": {},
        "accountLinkingStatus": "ACCOUNT_LINKING_STATUS_UNSPECIFIED",
        "verificationStatus": "VERIFIED",
        "packageEntitlements": [],
        "permissions": [
          "DEVICE_PRECISE_LOCATION"
        ],
        "lastSeenTime": "2021-02-08T20:43:47Z"
      },
      "home": {
        "params": {}
      },
      "device": {
        "capabilities": [
          "SPEECH",
          "RICH_RESPONSE",
          "LONG_FORM_AUDIO"
        ],
        "currentLocation": {
          "coordinates": {
            "latitude": 37.422,
            "longitude": -122.084
          },
          "postalAddress": {
            "revision": 0,
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94043",
            "sortingCode": "",
            "administrativeArea": "California",
            "locality": "Mountain View",
            "sublocality": "",
            "addressLines": ["1600 Amphitheatre Parkway"],
            "recipients": [],
            "organization": ""
          }
        }
      }
    }

למידע נוסף על הסכימה של סוג המיקום, ניתן לעיין במאמר קובץ עזר של Location.

אפשר לגשת למידע שנכלל בבקשה מה-webhook, כמו שמוצג בקטע הקוד הבא:

Webhook 
  app.handle('handler', (conv) => {
    let location = conv.device.currentLocation;
    conv.add(`Your postal code is ${location.postalCode}`);
  });

שימוש בהרשאה בהנחיות

אפשר גם להפנות להרשאה בהנחיות סטטיות. לדוגמה, עבור מיקום המכשיר, אפשר להשתמש ב-$device.currentLocation.coordinates.* וב-$device.currentLocation.postalAddress.*. קטע הקוד הבא מראה איך להפנות לעיר של המשתמש בהודעה:

candidates:
  - first_simple:
      variants:
        - speech: >-
            There are no events scheduled tomorrow in the city of $device.currentLocation.postalAddress.locality.