הרשאות

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

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

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

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

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

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

כדי להגדיר הרשאות ל-Action, מוסיפים סוג חדש של יחידות קיבולת (Slot) לסצנה. לאחר מכן מגדירים את יחידת הקיבולת (Slot) עבור הרשאת הנתונים שרוצים לבקש.

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

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

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

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

  5. בתפריט הנפתח Select type, בוחרים בסוג של יחידת הקיבולת actions.type.Permission.

  6. נותנים שם ליחידת הקיבולת (Slot) בשדה כאן.

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

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

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

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

קטע הקוד הבא מציג דוגמה להגדרה של יחידת קיבולת (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. בקטע Condition בסצנה, לוחצים על + כדי להוסיף תנאי חדש.

  4. מזינים את התנאי הבא כדי לבדוק את סטטוס ההרשאה (כאשר <משבצת_name> הוא השם של פרמטר הסשן שהגדרתם ביחידת הקיבולת):

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

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

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

    scene.slots.status == "FINAL"

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

  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.