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

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

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

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

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

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

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

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

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

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

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

ساختن اعلان برای یکپارچه‌سازی «ابر به ابر»

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

1. به Google اطلاع دهید که آیا اعلان‌ها از برنامه دستگاه smart home فعال هستند یا نه. اگر کاربران اعلان‌ها را در برنامه شما روشن یا خاموش کردند، درخواست 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 API برقرار کنید. درخواست 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 با فیلد 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 logging for Cloud-to-cloud توضیح داده شده است پشتیبانی می‌کنند. این گزارش‌ها برای آزمایش و حفظ کیفیت اعلان‌ها در «کنش» شما مفید هستند.

در زیر طرحواره ورودی notificationLog آمده است:

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

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

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