الأذونات

يمكنك استخدام الأذونات في الإجراء الخاص بك لطلب بيانات شخصية من المستخدم لأغراض إكمال الطلب. على سبيل المثال، قد يستخدم إجراء توصيل الطعام إذن تحديد الموقع الجغرافي للجهاز لطلب معلومات حول موقع المستخدم.

عند إضافة إذن إلى الإجراء الخاص بك، يقدّم "مساعد Google" واجهة عادية ومتسقة لطلب إذن من المستخدم بتقديم المعلومات إلى الإجراء الخاص بك.

الأذونات المتاحة

يمكن أن يطلب الإجراء الخاص بك الأذونات التالية:

  • DEVICE_PRECISE_LOCATION: تطلب هذه السمة الموقع الجغرافي الدقيق الخاص بجهاز المستخدم (الإحداثيات وعنوان الشارع).
  • DEVICE_COARSE_LOCATION: تطلب هذه السمة الموقع الجغرافي التقريبي لجهاز المستخدم (الرمز البريدي والمدينة).

إعداد الأذونات

لإعداد أذونات الإجراء الخاص بك، يجب إضافة نوع خانة جديد إلى المشهد. يمكنك بعد ذلك ضبط الخانة لإذن البيانات الذي تريد طلبه.

إضافة نوع خانة الأذونات

يمكنك منح الإجراء الخاص بك إمكانية الحصول على معلومات المستخدم من خلال نوع الخانة actions.type.Permission.

لضبط هذا النوع من الخانات، اتّبِع الخطوات التالية:

  1. انتقِل إلى وحدة تحكّم الإجراءات واختَر مشروعًا أو أنشئه.
  2. انقر على تطوير في القائمة بأعلى الصفحة.
  3. ضمن مشاهد، انقر على المشهد الذي تريد إضافة مسار الإذن إليه.
  4. ضمن القسم تعبئة الفتحة في المشهد، انقر على + لإضافة خانة جديدة.

  5. في القائمة المنسدلة اختيار النوع، اختَر نوع الخانة actions.type.Permission.

  6. في حقل إدخال اسم الخانة، أدخِل اسمًا للخانة.

  7. فعِّل كتابة قيمة الخانة المخصّصة لكتابة النتيجة إلى مَعلمة جلسة.

إعداد الخانة

يمكنك الآن توفير سلسلة سياق وقائمة بالأذونات التي سيتم منحها لضبط الخانة. سلسلة السياق هي الأساس المنطقي الذي يفسّر سبب طلبك للحصول على معلومات من المستخدم، ويتم عرضها للمستخدمين عندما يُطلب منهم منح الإذن للإجراء الخاص بك.

يمكنك ضبط سلسلة السياق والأذونات في قسم ضبط الخانة، كما هو موضّح في لقطة الشاشة التالية:

يعرض مقتطف الرمز التالي مثالاً على ضبط الخانة:

{
  "@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. انتقِل إلى وحدة تحكّم الإجراءات وانقر على تطوير في القائمة العلوية.
  2. ضمن لقطات، انقر على المشهد الذي يحتوي على خانة الإذن.
  3. ضمن قسم الشرط في المشهد، انقر على + لإضافة شرط جديد.

  4. أدخِل الشرط التالي للتحقق من حالة الإذن (حيث يكون <slot_name> هو اسم مَعلمة الجلسة التي ضبطتها في خانتك):

    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

قراءة معلومات المستخدم

إذا منح المستخدم الإذن، يتم تقديم معلومات المستخدم في الطلبات اللاحقة.

في المقتطف أدناه، يمكنك رؤية معلومات الموقع الجغرافي للجهاز المضمّنة في طلب الرد التلقائي على الويب ضمن 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.

يمكنك الوصول إلى المعلومات المضمّنة في الطلب من خلال الرد التلقائي على الويب، كما هو موضّح في المقتطف التالي:

الردّ التلقائي على الويب 
  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.