اعلان‌های مربوط به «کنش‌های» خانه هوشمند

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

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

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

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

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

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

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

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

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

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

ساختن اعلان‌ها برای ادغام «ابر به ابر»

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

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

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

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

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

با برقراری تماس درخواست همگام‌سازی برای به‌روزرسانی داده‌های دستگاه، به Google نشان دهید که اعلان‌ها برای دستگاهتان فعال شده است. هرگاه کاربران این تنظیم را در برنامه‌تان تغییر می‌دهند، باید درخواست SYNC را به این صورت ارسال کنید.

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

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

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

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

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

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

فعال کردن Google HomeGraph API

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

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

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

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

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

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

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

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

3. در فیلد نام حساب سرویس، نامی وارد کنید.

4. در فیلد شناسه حساب سرویس، شناسه‌ای وارد کنید.

5. در فیلد شرح حساب سرویس، شرحی وارد کنید.

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

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

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

9. روی تمام کلیک کنید.

10. حساب سرویسی را که به‌تازگی ایجاد کرده‌اید از فهرست حساب‌های سرویس انتخاب کنید و مدیریت کلیدها را از منوِ more_vert کنش‌ها انتخاب کنید.

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

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

13. روی ایجاد کردن کلیک کنید. فایل JSON حاوی کلیدتان در رایانه بارگیری می‌شود.

ارسال اعلان

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

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

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

• ارسال بار داده اعلان پیش‌کنشی
• ارسال بار داده پاسخ پیگیری

ارسال محموله اعلان پیش‌کنشی

برای فراخوانی 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 ارائه شده است. 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"
          }
        }]
      }]
    }
  }]
};

Google از 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);
    

ثبت

اعلان‌ها از ثبت رویداد پشتیبانی می‌کنند، همان‌طور که در ثبت Cloud برای Cloud-to-cloud توضیح داده شده است. این گزارش‌ها برای آزمایش و حفظ کیفیت اعلان‌ها در «کنش» شما مفید هستند.

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

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

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

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