اعلان‌ها برای اقدامات خانه هوشمند

اعلان‌ها به یکپارچه‌سازی Cloud-to-cloud شما اجازه می‌دهند تا Google Assistant برای ارتباط با کاربران در مورد رویدادها یا تغییرات مهم مربوط به دستگاه استفاده کند. می‌توانید اعلان‌ها را برای هشدار به کاربران در مورد رویدادهای به موقع دستگاه، مثلاً زمانی که کسی پشت در است، یا برای گزارش تغییر وضعیت درخواستی دستگاه، مانند زمانی که قفل درب با موفقیت باز شده یا گیر کرده است، پیاده‌سازی کنید.

ادغام Cloud-to-cloud شما می‌تواند انواع اعلان‌های زیر را برای کاربران ارسال کند:

• اعلان‌های پیشگیرانه : بدون هیچ درخواست قبلی کاربر از دستگاه‌های smart home ، مانند زنگ در، کاربر را از رویدادی در دستگاه هوشمند مطلع می‌کند.

• پاسخ‌های پیگیری : تأییدیه‌ای مبنی بر موفقیت‌آمیز بودن یا نبودن درخواست دستور دستگاه، مثلاً هنگام قفل کردن در. از این هشدارها برای دستورات دستگاه که تکمیل آنها زمان می‌برد، استفاده کنید. پاسخ‌های پیگیری فقط زمانی پشتیبانی می‌شوند که درخواست‌های دستور دستگاه از بلندگوهای هوشمند و نمایشگرهای هوشمند ارسال شوند.

Assistant این اعلان‌ها را به صورت اعلان‌هایی در بلندگوهای هوشمند و نمایشگرهای هوشمند به کاربران ارائه می‌دهد. اعلان‌های فعال به طور پیش‌فرض غیرفعال هستند. کاربران می‌توانند همه اعلان‌های فعال را از Google Home app (GHA) روشن یا خاموش کنند.

رویدادهایی که اعلان‌ها را فعال می‌کنند

وقتی رویدادهای دستگاه رخ می‌دهد، بخش سفارشات شما یک درخواست اعلان به گوگل ارسال می‌کند. ویژگی‌های دستگاهی که ادغام Cloud-to-cloud شما پشتیبانی می‌کند، تعیین می‌کند که چه نوع رویدادهای اعلانی در دسترس هستند و چه داده‌هایی را می‌توانید در آن اعلان‌ها بگنجانید.

ویژگی‌های زیر از اعلان‌های پیشگیرانه پشتیبانی می‌کنند:

ویژگی‌های زیر از پاسخ‌های تکمیلی پشتیبانی می‌کنند:

همه انواع دستگاه‌ها از اعلان‌ها برای ویژگی‌های مربوطه پشتیبانی می‌کنند.

برای ادغام ابر به ابر خود، اعلان بسازید

اعلان‌ها را در این مراحل به ادغام Cloud-to-cloud خود اضافه کنید:

1. اگر اعلان‌ها از برنامه دستگاه smart home شما فعال هستند، به گوگل اطلاع دهید. اگر کاربران اعلان‌ها را در برنامه شما فعال یا غیرفعال می‌کنند، یک درخواست SYNC ارسال کنید تا گوگل را از تغییر دستگاه مطلع کنید.
2. وقتی یک رویداد یا تغییر وضعیت دستگاه رخ می‌دهد که باعث ایجاد یک اعلان می‌شود، با فراخوانی API Report State reportStateAndNotification یک درخواست اعلان ارسال کنید. اگر وضعیت دستگاه تغییر کرد، می‌توانید هم وضعیت و هم بار داده اعلان را در فراخوانی Report State و Notification خود با هم ارسال کنید.

بخش‌های بعدی این مراحل را با جزئیات بیشتری پوشش می‌دهند.

مشخص کنید که آیا اعلان‌ها در برنامه شما فعال هستند یا خیر

کاربران می‌توانند با فعال کردن این ویژگی در GHA ، انتخاب کنند که آیا می‌خواهند اعلان‌های پیشگیرانه دریافت کنند یا خیر. در برنامه دستگاه smart home خود، می‌توانید به صورت اختیاری قابلیتی را اضافه کنید که کاربران بتوانند اعلان‌ها را از دستگاه، مثلاً از تنظیمات برنامه، به طور صریح تغییر دهند.

با ایجاد یک درخواست همگام‌سازی (Request SYNC) برای به‌روزرسانی داده‌های دستگاه، به گوگل اطلاع دهید که اعلان‌ها برای دستگاه شما فعال شده‌اند. هر زمان که کاربران این تنظیم را در برنامه شما تغییر می‌دهند، باید یک درخواست SYNC مانند این ارسال کنید.

در پاسخ SYNC خود، یکی از این به‌روزرسانی‌ها را ارسال کنید:

• اگر کاربر به صراحت اعلان‌ها را در برنامه دستگاه شما فعال کرده است، یا اگر گزینه‌ای برای فعال کردن اعلان‌ها ارائه نداده‌اید، ویژگی devices.notificationSupportedByAgent را روی true تنظیم کنید.
• اگر کاربر صراحتاً اعلان‌ها را در برنامه دستگاه شما غیرفعال کرده است، ویژگی devices.notificationSupportedByAgent را روی false تنظیم کنید.

قطعه کد زیر مثالی از نحوه تنظیم پاسخ SYNC شما را نشان می‌دهد:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

ارسال درخواست‌های اعلان به گوگل

برای فعال کردن اعلان‌ها در Assistant ، درخواست شما از طریق فراخوانی API Report State و اعلان ، یک بار داده اعلان را به Google Home Graph ارسال می‌کند.

فعال کردن API گوگل هوم‌گراف

1. در Google Cloud Console ، به صفحه HomeGraph API بروید.

   به صفحه HomeGraph API بروید
2. پروژه‌ای را انتخاب کنید که با شناسه پروژه smart home شما مطابقت داشته باشد.
3. روی فعال کردن (ENABLE) کلیک کنید.

ایجاد کلید حساب سرویس

برای تولید کلید حساب سرویس از Google Cloud Console این دستورالعمل‌ها را دنبال کنید:

1. در Google Cloud Console ، به صفحه حساب‌های سرویس بروید.

   به صفحه حساب‌های سرویس بروید .

   ممکن است لازم باشد قبل از اینکه به صفحه حساب‌های سرویس هدایت شوید، یک پروژه را انتخاب کنید.

2. روی add کلیک کنید. ایجاد حساب کاربری سرویس .

3. در قسمت نام حساب سرویس ، یک نام وارد کنید.

4. در قسمت شناسه حساب سرویس ، یک شناسه وارد کنید.

5. در قسمت توضیحات حساب سرویس ، توضیحی وارد کنید.

6. روی ایجاد کلیک کنید و ادامه دهید .

7. از منوی کشویی نقش ، حساب‌های سرویس > حساب سرویس OpenID Connect Identity Token Creator را انتخاب کنید.

8. روی ادامه کلیک کنید.

9. روی انجام شد کلیک کنید.

10. حساب سرویسی که ایجاد کرده‌اید را از فهرست حساب‌های سرویس انتخاب کنید و از منوی more_vert Actions گزینه Manage keys را انتخاب کنید.

11. افزودن کلید > ایجاد کلید جدید را انتخاب کنید.

12. برای نوع کلید ، گزینه JSON را انتخاب کنید.

13. روی «ایجاد» کلیک کنید. یک فایل JSON که حاوی کلیدهای دانلود شده روی رایانه شماست.

ارسال اعلان

با استفاده از API مربوط به devices.reportStateAndNotification ، درخواست اعلان را فراخوانی کنید. درخواست JSON شما باید شامل یک eventId باشد که یک شناسه منحصر به فرد است که توسط پلتفرم شما برای رویدادی که اعلان را فعال می‌کند، تولید می‌شود. eventId باید یک شناسه تصادفی باشد که هر بار که درخواست اعلان ارسال می‌کنید، متفاوت است.

در شیء notifications که در فراخوانی API خود ارسال می‌کنید، یک مقدار priority قرار دهید که نحوه نمایش اعلان را تعریف می‌کند. شیء notifications شما ممکن است بسته به ویژگی دستگاه، فیلدهای مختلفی داشته باشد.

برای تنظیم payload و فراخوانی API، یکی از این مسیرها را دنبال کنید:

• ارسال یک بار اطلاع رسانی پیشگیرانه
• ارسال یک بسته پاسخ پیگیری

ارسال یک بار اطلاع رسانی پیشگیرانه

برای فراخوانی API، یکی از گزینه‌های زیر را انتخاب کنید:

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Build device notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
    

ارسال یک بسته پاسخ پیگیری

بار داده برای پاسخ پیگیری شامل وضعیت درخواست، کدهای خطا برای خطاهای رویداد، در صورت وجود، و followUpToken معتبر ارائه شده در طول درخواست EXECUTE intent است. followUpToken باید ظرف پنج دقیقه استفاده شود تا معتبر باقی بماند و پاسخ را به درستی با درخواست اصلی مرتبط کند.

قطعه کد زیر نمونه‌ای از یک درخواست EXECUTE با فیلد followUpToken را نشان می‌دهد.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

گوگل از followUpToken برای نمایش اعلان فقط روی دستگاهی که کاربر در ابتدا با آن تعامل داشته استفاده می‌کند و آن را در تمام دستگاه‌های کاربر پخش نمی‌کند.

برای فراخوانی API، یکی از گزینه‌های زیر را انتخاب کنید:

const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});
    

// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);
    

ثبت وقایع

اعلان‌ها از ثبت وقایع همانطور که در ثبت وقایع ابری برای ابر به ابر شرح داده شده است، پشتیبانی می‌کنند. این گزارش‌ها برای آزمایش و حفظ کیفیت اعلان‌ها در اکشن شما مفید هستند.

طرح کلی یک ورودی notificationLog به صورت زیر است:

فیلد status شامل وضعیت‌های مختلفی است که ممکن است نشان‌دهنده‌ی خطاهایی در محتوای اعلان باشند. برخی از این موارد ممکن است فقط در اکشن‌هایی که هنوز به مرحله‌ی تولید نرسیده‌اند، در دسترس باشند.

مثال‌هایی از وضعیت‌ها عبارتند از:

علاوه بر این وضعیت‌های عمومی که می‌توانند برای همه اعلان‌ها اعمال شوند، فیلد status می‌تواند در صورت لزوم شامل وضعیت‌های خاص مربوط به یک ویژگی نیز باشد (برای مثال، OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING ).