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

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

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

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

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

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

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

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

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

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

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

برای ادغام Cloud-to-Cloud خود اعلان بسازید

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

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

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

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

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

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

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

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

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

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

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

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

Google HomeGraph API را فعال کنید

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

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

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

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

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

   به صفحه Create Service Account Key بروید
2. از لیست حساب سرویس ، حساب سرویس جدید را انتخاب کنید.
3. در قسمت نام حساب سرویس ، یک نام وارد کنید.
4. در قسمت شناسه حساب سرویس ، یک شناسه وارد کنید.

5. از فهرست نقش ، حساب‌های خدمات > ایجاد کننده رمز حساب حساب را انتخاب کنید.

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

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

اطلاعیه را ارسال کنید

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

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

برای تنظیم بار و فراخوانی 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 ارائه شده است. followUpToken باید در عرض پنج دقیقه استفاده شود تا معتبر بماند و پاسخ به درخواست اصلی به درستی مرتبط شود.

قطعه زیر نمونه ای از EXECUTE request payload را با فیلد 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 ذکر شده است. این گزارش‌ها برای آزمایش و حفظ کیفیت اعلان‌ها در Action شما مفید هستند.

شکل زیر طرح یک ورودی notificationLog است:

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

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

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