iOS 裝置適用的門鈴裝置指南

門鈴裝置類型是透過兩種特徵實作：PushAvStreamTransportTrait，可使用以推送為基礎的通訊協定處理音訊和影片串流傳輸；WebRtcLiveViewTrait，可控制即時串流和對講功能。

使用任何功能或嘗試更新屬性之前，請務必先檢查裝置是否支援屬性和指令。詳情請參閱「透過iOS 控制裝置」。

Home API 裝置類型特徵 Swift 範例應用程式用途

Home API 裝置類型	特徵	Swift 範例應用程式	用途
門鈴 `GoogleDoorbellDeviceType` `home.matter.6006.types.0113` 門外的按鈕啟動裝置，會發出聲音和/或視覺信號，用於請求門另一側的人注意。門鈴可能提供無障礙直播、雙向對講或偵測事件。	必要特徵 google PushAvStreamTransportTrait google WebRtcLiveViewTrait		門鈴

門鈴

GoogleDoorbellDeviceType

home.matter.6006.types.0113

門外的按鈕啟動裝置，會發出聲音和/或視覺信號，用於請求門另一側的人注意。門鈴可能提供無障礙直播、雙向對講或偵測事件。

必要特徵
google PushAvStreamTransportTrait
google WebRtcLiveViewTrait

門鈴

取得裝置的基本資訊

BasicInformation 特徵包括供應商名稱、供應商 ID、產品 ID、產品名稱 (包括型號資訊)、軟體版本和裝置序號等資訊：

// [START get_device_information]
let vendorName = basicInfoTrait.attributes.vendorName!
let vendorID = basicInfoTrait.attributes.vendorID!
let productID = basicInfoTrait.attributes.productID!
let productName = basicInfoTrait.attributes.productName!
let softwareVersion = basicInfoTrait.attributes.softwareVersion!
let serialNumber = basicInfoTrait.attributes.serialNumber!
// [END get_device_information]

取得裝置與雲端連線的最新時間

如要找出裝置最近一次與雲端連線的時間，請使用 ExtendedGeneralDiagnostics 特徵的 lastContactTimestamp 屬性：

if let lastContactTimeStamp = extendedGeneralDiagnosticsTrait.attributes.lastContactTimestamp {
  self.lastContactTime = Date(timeIntervalSince1970: Double(lastConnectedTimeStamp))
}

檢查裝置的連線狀態

裝置的連線狀態實際上是在裝置類型層級檢查，因為部分裝置支援多種裝置類型。傳回的狀態是該裝置上所有特徵的連線狀態組合。

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

如果沒有網際網路連線，混合裝置類型可能會顯示 partiallyOnline 狀態。Matter標準特徵可能仍會因本機路由而保持連線，但雲端特徵會離線。

開始直播

如要開始直播，請將工作階段描述通訊協定 (SDP) 字串傳送至 WebRtcLiveViewTrait 特徵的 startLiveView(offerSdp:) 方法，該方法會傳回三個值：

工作階段的 SDP。
工作階段持續時間 (以秒為單位)。
工作階段 ID，可用於延長或終止工作階段。

public func sendOffer(offerSdp: String) async throws
-> (answerSdp: String, mediaSessionId: String, liveViewDuration: TimeInterval)
{
  do {
    // Sending StartLiveView command
    let response = try await liveViewTrait.startLiveView(
      offerSdp: offerSdp
    )
    // Received StartLiveView response
    return (
      answerSdp: response.answerSdp,
      mediaSessionId: response.mediaSessionId,
      liveViewDuration: TimeInterval(response.liveSessionDurationSeconds)
    )
  } catch {
    // Failed to send StartLiveView command
    throw error
  }
}

延長直播時間

直播有預設時限，超過時限就會過期。如要延長有效串流的時長，請使用 extendLiveView(mediaSessionId:optionalArgsProvider:) 方法發出延長要求：

public func extendLiveView(mediaSessionId: String) async throws {
  do {
    // Extending live view
    let extendedDuration = try await liveViewTrait.extendLiveView(mediaSessionId: mediaSessionId)
  } catch {
    // Failed to extend live view
    throw error
  }
}

啟動及停止 TalkBack

如要啟動 TalkBack，請呼叫 WebRtcLiveViewTrait 特徵的 startTalkback(mediaSessionId:optionalArgsProvider:) 方法。如要停止，請使用 stopTalkback(mediaSessionId:)。

public func toggleTwoWayTalk(isOn: Bool, mediaSessionId: String) async throws {
  do {
    if isOn {
      try await liveViewTrait.startTalkback(mediaSessionId: mediaSessionId)
    } else {
      try await liveViewTrait.stopTalkback(mediaSessionId: mediaSessionId)
    }
  } catch {
    throw HomeError.commandFailed("Failed to toggle twoWayTalk: \(error)")
  }
}

啟用及停用錄製功能

如要啟用攝影機的錄影功能，請將 TransportStatusEnum.Active 傳遞至 PushAvStreamTransportTrait 特徵的 setTransportStatus(transportStatus:optionalArgsProvider:) 方法。如要停用錄音功能，請傳遞 TransportStatusEnum.Inactive。在以下範例中，我們將這些呼叫納入單一呼叫中，並使用 Boolean 切換錄音功能：

public func toggleIsRecording(isOn: Bool) {
  self.uiState = .loading

  guard let pushAvStreamTransportTrait else {
    // PushAvStreamTransportTrait not found.
    return
  }
  Task {
    do {
      try await pushAvStreamTransportTrait.setTransportStatus(
        transportStatus: isOn ? .active : .inactive)
      if isOn {
        do {
          self.player = try self.createWebRtcPlayer()
        } catch {
          // Failed to initialize WebRtcPlayer
          self.uiState = .disconnected
          return
        }
        await self.player?.initialize()
        self.uiState = .live
      } else {
        self.player = nil
        self.uiState = .off
      }
    } catch {
      // Failed to toggle onOff
    }
  }
}

啟用或停用攝影機的錄影功能，等同於開啟或關閉攝影機影像。攝影機影像開啟時，攝影機就會錄影 (用於事件和相關影像片段)。

錄製功能停用時 (攝影機影片關閉)：

攝影機仍會顯示為connectivityState裝置類型的線上狀態。
無法存取直播，攝影機也未偵測到任何雲端事件。

確認是否已啟用錄製功能

如要判斷攝影機是否已啟用錄影功能，請檢查是否有任何連線處於啟用狀態。以下範例定義了兩個函式來執行這項操作：

public func isDeviceRecording() -> Bool {
  guard let pushAvStreamTransportTrait else {
    // PushAvStreamTransportTrait not found.
    return false
  }
  guard
    let hasActiveConnection =
      pushAvStreamTransportTrait
      .attributes
      .currentConnections?
      .contains(where: { $0.transportStatus == .active })
  else {
    return false
  }
  return hasActiveConnection
}

電池設定

你可以透過 Home API 控制各種電池設定。

設定電池用量偏好設定

設定能源平衡可讓您在裝置的電池續航力和效能之間取捨。你可以建立不同的電池設定檔，例如「延長續航力」、「平衡」和「效能」，並在這些設定檔之間切換。

如要實作這項功能，請更新 EnergyPreference 特徵的 currentEnergyBalance 屬性。這個屬性接受與裝置 energyBalances 清單中定義的特定設定檔對應的整數索引 (例如 EXTENDED 的 0、BALANCED 的 1，以及 PERFORMANCE 的 2)。

currentEnergyBalance 的 null 值表示裝置使用自訂設定檔。這是唯讀狀態。

以下範例顯示 currentEnergyBalance 屬性使用的結構，接著是使用該屬性的實際程式碼片段。

// Example energyBalances list
{
  "energy_balances": [
    {
      "step": 0,
      "label": "EXTENDED"
    },
    {
      "step": 50,
      "label": "BALANCED"
    },
    {
      "step": 100,
      "label": "PERFORMANCE"
    }
  ]
}

private func setBatteryUsage(to option: UInt8) async throws {
  _ = try await energyPreferenceTrait.update {
    $0.setCurrentEnergyBalance(option)
  }
}

開啟自動省電模式

如要設定這項功能，請更新 EnergyPreference 特徵的 currentLowPowerModeSensitivity 屬性。這項屬性會使用索引選取敏感度等級，其中 0 通常代表 Disabled，而 1 代表 Enabled 或 Automatic。

private func setAutoBatterySaver(to value: Bool) async throws {
  _ = try await energyPreferenceTrait.update {
    $0.setCurrentLowPowerModeSensitivity(value ? 1 : 0)
  }
}

取得電池充電狀態

如要取得裝置目前的充電狀態 (充電中、已充飽電或未充電)，請使用 PowerSource 特徵的 batChargeState 屬性。

self.chargingState = powerSourceTrait.attributes.batChargeState

var description: String
switch self.chargingState {
case .isCharging:
  description = "Charging"
case .isAtFullCharge:
  description = "Full"
case .isNotCharging:
  description = "Not Charging"
default:
  description = "Unknown"
}

取得電池電量

如要取得目前的電池電量，請使用 PowerSource 特徵的 batChargeLevel 屬性。層級可以是 OK、Warning (低) 或 Critical。

self.batteryLevel = powerSourceTrait.attributes.batChargeLevel

var description: String
switch self.batteryLevel {
case .ok:
  description = "OK"
case .warning:
  description = "Warning"
case .critical:
  description = "Critical"
default:
  description = "Unknown"
}

取得電源

如要判斷裝置使用的電源，請使用 PowerSource 特徵的 BatPresent 和 wiredPresent 屬性。

if powerSourceTrait.attributes.wiredPresent ?? false {
  self.powerSourceType = .wired
} else if powerSourceTrait.attributes.batPresent ?? false {
  self.powerSourceType = .battery
} else {
  self.powerSourceType = nil
}

音訊設定

你可以透過 Home API 控制各種音訊設定。

開啟或關閉麥克風

如要開啟或關閉裝置麥克風，請使用內建的 setMicrophoneMuted 函式，更新 CameraAvStreamManagementTrait 特徵的 microphoneMuted 屬性：

// Turn the device's microphone on or off
func setMicrophone(on: Bool) async {
  do {
    _ = try await self.cameraAvStreamManagementTrait?.update {
      $0.setMicrophoneMuted(!on)
    }
  } catch {
    // Error
  }
}

開啟或關閉音訊錄音功能

如要開啟或關閉裝置的音訊錄音功能，請使用內建的 setRecordingMicrophoneMuted 函式，更新 CameraAvStreamManagementTrait 特徵的 recordingMicrophoneMuted 屬性：

// Turn audio recording on or off for the device
func setAudioRecording(on: Bool) async {
  do {
    _ = try await self.cameraAvStreamManagementTrait?.update {
      $0.setRecordingMicrophoneMuted(!on)
    }
  } catch {
    // Error
  }
}

調整音箱音量

如要調整裝置的音箱音量，請使用內建的 setSpeakerVolumeLevel 函式，更新 CameraAvStreamManagementTrait 特徵的 speakerVolumeLevel 屬性：

// Adjust the camera speaker volume
func setSpeakerVolume(to value: UInt8) async {
  do {
    _ = try await cameraAvStreamManagementTrait.update {
      $0.setSpeakerVolumeLevel(value)
    }
  } catch {
    // Error
  }
}

活動區設定

ZoneManagement 特徵提供介面，可管理攝影機和門鈴裝置上的自訂感興趣區域 (活動區)。這些區域可用於篩選裝置視野內特定區域的事件偵測結果 (例如人物或車輛移動)。

使用者可在合作夥伴應用程式中設定活動區，在攝影機視野的特定區域繪製活動區。這些使用者定義的區域隨後會轉換為這個特徵所用的結構。如要進一步瞭解活動區的運作方式，請參閱「設定及使用活動區」一文。

活動區通常是使用 2D 直角座標定義。這個特徵會提供頂點的 TwoDCartesianVertexStruct，以及區域定義 (名稱、頂點、顏色和用途) 的 TwoDCartesianZoneStruct。

查看活動區

如要顯示活動區，請檢查 ZoneManagement 特徵的 zones 屬性。

let zoneManagementTrait: Google.ZoneManagementTrait

self.zones = zoneManagementTrait.attributes.zones ?? []

新增活動區

如要建立新區域，請使用 createTwoDCartesianZone 指令。這項指令會採用 TwoDCartesianZoneStruct，定義區域的名稱、頂點、顏色和用途。

以下範例說明如何建立名為「前廊」的區域，其中包含四個頂點，顏色為鮭魚色 (#F439A0)，並用於動作偵測。

import GoogleHomeSDK
import GoogleHomeTypes

func createFrontPorchZone(trait: Google.ZoneManagementTrait) async {
  // 1. Define the vertices for the zone (2D Cartesian coordinates)
  // Values are UInt16, typically scaled to the device's twoDCartesianMax.
  let vertices = [
    Google.ZoneManagementTrait.TwoDCartesianVertexStruct(x = 260, y = 422),
    Google.ZoneManagementTrait.TwoDCartesianVertexStruct(x = 1049, y = 0),
    Google.ZoneManagementTrait.TwoDCartesianVertexStruct(x = 2048, y = 0),
    Google.ZoneManagementTrait.TwoDCartesianVertexStruct(x = 2048, y = 950),
    Google.ZoneManagementTrait.TwoDCartesianVertexStruct(x = 1630, y = 1349),
    Google.ZoneManagementTrait.TwoDCartesianVertexStruct(x = 880, y = 2048),
    Google.ZoneManagementTrait.TwoDCartesianVertexStruct(x = 0, y = 2048),
    Google.ZoneManagementTrait.TwoDCartesianVertexStruct(x = 638, y = 1090)
  ]

  // 2. Define the zone structure using the given SDK struct
  let newZone = Google.ZoneManagementTrait.TwoDCartesianZoneStruct(
    name: "Front Porch",
    use: [.motion], // ZoneUseEnum.motion
    vertices: vertices,
    // Color is a hex string (for example, Salmon/Pink)
    color: "#F439A0"
  )

  do {
    // 3. Execute the raw command to add the zone to the device
    // This returns the created zone's ID (UInt16).
    var newZoneID = try await trait.createTwoDCartesianZone(zone: newZone)
  } catch {
    // Error
  }
}

更新活動區

如要更新現有區域，請使用 updateTwoDCartesianZone 指令。這項指令需要 zoneId 和更新後的 TwoDCartesianZoneStruct。

let zoneManagementTrait: Google.ZoneManagementTrait
let zoneID: UInt16
let zone: Google.ZoneManagementTrait.TwoDCartesianZoneStruct

do {
  _ = try await zoneManagementTrait.updateTwoDCartesianZone(
        zoneID: zoneID, zone: zone)
} catch {
  // Error
}

刪除活動區

如要移除區域，請使用 removeZone 指令搭配特定 zoneId。

let zoneManagementTrait: Google.ZoneManagementTrait
let zoneID: UInt16

do {
  _ = try await zoneManagementTrait.removeZone(zoneID: zoneID)
} catch {
  // Error
}

聲響偵測事件觸發條件

AvStreamAnalysis 特徵提供介面，可管理攝影機和門鈴裝置的事件偵測觸發條件。以影像為準的觸發條件 (例如人或車輛) 可指定區域，但聲音相關的觸發條件通常是裝置層級的設定。

使用 EventTriggerTypeEnum 進行聲響偵測時，可用的觸發條件類型如下：

模式	列舉值	說明
音效	`Sound`	一般聲響偵測。
有人說話	`PersonTalking`	偵測語音。
狗吠聲	`DogBark`	偵測犬隻的叫聲。
玻璃碎裂	`GlassBreak`	偵測玻璃破裂聲。
煙霧警報	`SmokeAlarm`	偵測煙霧警報器，通常會辨識 T3 可聽見的模式 (三聲短促的嗶聲，然後暫停)。
一氧化碳警報	`CoAlarm`	偵測一氧化碳 (CO) 警報，通常會以 T4 聲音模式 (四聲短促的嗶聲，接著暫停) 辨識。

查看聲響偵測狀態

如要向使用者顯示聲響偵測的目前狀態，請務必檢查裝置支援的項目，以及裝置硬體啟用的項目。要檢查的屬性有兩個：

在 iOS 開發中，您通常會從裝置存取 AvStreamAnalysis 特徵，以讀取這些屬性。

// Example struct to store event triggers
public struct EventTrigger: Equatable {
  public var id: Google.AvStreamAnalysisTrait.EventTriggerTypeEnum
  public var enabled: Bool
}

let avStreamAnalysisTrait: Google.AvStreamAnalysisTrait

let possibleEventTriggers = avStreamAnalysisTrait.attributes.supportedEventTriggers ?? []
let enabledEventTriggers = avStreamAnalysisTrait.attributes.enabledEventTriggers ?? []

let eventTriggers [EventTrigger] = []
for trigger in possibleEventTriggers {
  self.eventTriggers.append(
    EventTrigger(
      id: trigger,
      enabled: enabledEventTriggers.contains(trigger)
    )
  )
}

更新已啟用觸發條件的集合

如要更新已啟用觸發條件的集合，請使用 SetOrUpdateEventDetectionTriggers 指令，該指令會採用 EventTriggerEnablement 結構清單。

// Example struct to store event triggers
public struct EventTrigger: Equatable {
  public var id: Google.AvStreamAnalysisTrait.EventTriggerTypeEnum
  public var enabled: Bool
}

let avStreamAnalysisTrait: Google.AvStreamAnalysisTrait
let eventTriggers: [EventTrigger]

let enabledEventTriggers = eventTriggers.map {
  Google.AvStreamAnalysisTrait.EventTriggerEnablement(
    eventTriggerType: $0.id,
    enablementStatus: $0.enabled ? .enabled : .disabled
  )
}

try await avStreamAnalysisTrait.setOrUpdateEventDetectionTriggers(
  eventTriggerEnablements: enabledEventTriggers
)

錄製模式

RecordingMode 特徵提供介面，可管理攝影機和門鈴裝置的影片和圖片錄製行為。使用者可以選擇連續錄影、事件錄影，或完全停用錄影功能 (僅限即時監控)。

RecordingModeEnum 定義可用的記錄策略：

模式	列舉值	說明
已停用	`Disabled`	錄製功能已完全停用。主要用於舊版裝置。
CVR (連續錄影)	`Cvr`	攝影機全天候錄影，須訂閱 (例如 Google Google Home Premium)。
事件錄影	`Ebr`	錄影功能會由事件 (人員、動作) 觸發。影片長度取決於活動時間長度和訂閱方案。
ETR (事件觸發錄影)	`Etr`	事件觸發的短時間預錄內容 (例如 10 秒)。
實景	`LiveView`	錄製功能已停用，但使用者仍可觀看直播。
靜態圖片	`Images`	發生事件時，系統會錄製快照，而非影片。

檢查錄製模式

如要顯示目前的錄製設定，請檢查 RecordingMode 特徵的屬性：

supportedRecordingModes - 所有可能模式
availableRecordingModes - 可選取的模式
selectedRecordingMode - 正常模式

// Example struct to store recording modes.
public struct RecordingMode: Hashable {
  public let id: UInt8
  public let mode: Google.RecordingModeTrait.RecordingModeEnum
}

let recordingModeTrait: Google.RecordingModeTrait

if let availableRecordingModes = recordingModeTrait.attributes.availableRecordingModes,
   let supportedRecordingModes = recordingModeTrait.attributes.supportedRecordingModes,
   let selectedRecordingMode = recordingModeTrait.attributes.selectedRecordingMode {

  var recordingModes: [RecordingMode] = []

  for recordingModeId in availableRecordingModes {
    guard Int(recordingModeId) < supportedRecordingModes.count,
          Int(recordingModeId) >= 0 else {
      // Out of bounds error
    }

    recordingModes.append(
      RecordingMode(
        id: recordingModeId,
        mode: supportedRecordingModes[Int(recordingModeId)].recordingMode,
      )
    )
  }
}

變更錄製模式

更新前，請確認 supportedRecordingModes 屬性中選擇的索引位於 availableRecordingModes 屬性中。

如要更新所選模式，請使用 setSelectedRecordingMode 函式，並傳遞所選模式的索引：

let recordingModeTrait: Google.RecordingModeTrait
let recordingModeID: UInt8

_ = try await recordingModeTrait.update {
  $0.setSelectedRecordingMode(recordingModeID)
}

其他設定

您也可以透過 Home API 控制其他設定。

開啟或關閉夜視模式

如要開啟或關閉攝影機的夜視功能，請使用 TriStateAutoEnum 更新 CameraAvStreamManagementTrait 特徵的 nightVision 屬性，方法是使用內建的 setNightVision 函式：

// Turn night vision on or off
func setNightVision(
  to value: Google.CameraAvStreamManagementTrait.TriStateAutoEnum
) async {
  do {
    _ = try await cameraAvStreamManagementTrait.update {
      $0.setNightVision(value)
    }
  } catch {
    // Error
  }
}

變更狀態 LED 燈的亮度

如要變更狀態 LED 的亮度，請使用 ThreeLevelAutoEnum 更新 statusLightBrightness CameraAvStreamManagementTrait 特徵的屬性，方法是使用內建的 setStatusLightBrightness 函式：

// Set the LED brightness
func setStatusLightBrightness(
  to value: Google.CameraAvStreamManagementTrait.ThreeLevelAutoEnum
) async {
  do {
    _ = try await cameraAvStreamManagementTrait.update {
      $0.setStatusLightBrightness(value)
    }
  } catch {
    // Error
  }
}

變更攝影機可視區域

攝影機檢視區塊與「縮放加強 Nest 攝影機影像」支援文章中說明的「縮放及裁剪」功能相同。

視埠定義於包含四個值的 ViewportStruct 中，這些值會做為視埠的座標。座標定義如下：

(x1,y1) -- (x2,y1)
   |          |
(x1,y2) -- (x2,y2)

判斷 ViewportStruct 的值取決於應用程式的 UI 和相機實作方式。在最基本的層級，如要設定攝影機影片的檢視區塊，請使用內建的 setViewport 函式，透過 ViewportStruct 更新 CameraAvStreamManagementTrait 特徵的 viewport 屬性。

func setCrop(x1: UInt16, y1: UInt16, x2: UInt16, y2: UInt16) {

  let viewport = Google.CameraAvStreamManagementTrait.ViewportStruct(
    x1: x1,
    y1: y1,
    x2: x2,
    y2: y2
  )

  Task {
    do {
      try await cameraAvStreamManagementTrait.update {
        $0.setViewport(viewport)
      }
    } catch {
      // Error
    }
  }

}

產生 TransportOptionsStruct

部分設定需要修改 TransportOptionsStruct 中的屬性，然後傳遞至串流連線的傳輸選項。如果是 Swift，更新任何屬性前，必須先產生這個結構體。

使用這個輔助函式產生結構體，以便用於下列設定變更：

調整裝置喚醒靈敏度
調整事件錄影時間上限

func getTransportOptions(
  transportOptions: Google.PushAvStreamTransportTrait.TransportOptionsStruct,
  wakeUpSensitivity: UInt8?,
  maxEventLength: UInt32?
) async throws
  -> Google.PushAvStreamTransportTrait.TransportOptionsStruct
{

  var newMotionTimeControl:
    Google.PushAvStreamTransportTrait.TransportMotionTriggerTimeControlStruct? = nil
  if let maxEventLength {
    guard let motionTimeControl = transportOptions.triggerOptions.motionTimeControl else {
      throw HomeError.failedPrecondition(
        // Error - cannot update max event length without motion time control
    }
    newMotionTimeControl =
      Google.PushAvStreamTransportTrait.TransportMotionTriggerTimeControlStruct(
        initialDuration: motionTimeControl.initialDuration,
        augmentationDuration: motionTimeControl.augmentationDuration,
        maxDuration: maxEventLength,
        blindDuration: motionTimeControl.blindDuration
      )
  }

  return Google.PushAvStreamTransportTrait.TransportOptionsStruct(
    streamUsage: .recording,
    videoStreamID: nil,
    audioStreamID: nil,
    tlsEndpointID: transportOptions.tlsEndpointID,
    url: transportOptions.url,
    triggerOptions: Google.PushAvStreamTransportTrait.TransportTriggerOptionsStruct(
      triggerType: .motion,
      motionZones: nil,
      motionSensitivity: wakeUpSensitivity,
      motionTimeControl: newMotionTimeControl,
      maxPreRollLen: nil
    ),
    ingestMethod: .cmafIngest,
    containerOptions: Google.PushAvStreamTransportTrait.ContainerOptionsStruct(
      containerType: .cmaf,
      cmafContainerOptions: nil
    ),
    expiryTime: nil
  )
}

private func getRecordingConnection() async throws
  -> Google.PushAvStreamTransportTrait.TransportConfigurationStruct?
{
  guard let pushAvStreamTransportTrait else {
    // Error - PushAvStreamTransport trait not available
    return nil
  }

  let connections = try await pushAvStreamTransportTrait.findTransport().transportConfigurations

  for connection in connections {
    guard let transportOptions = connection.transportOptions,
      transportOptions.streamUsage == .recording
    else {
      continue
    }

    return connection
  }

  return nil
}

調整裝置喚醒靈敏度

裝置的喚醒敏感度可縮減裝置感應活動的範圍，並延長偵測到活動後喚醒裝置的時間，藉此節省電力。

在 Home API 中，這項屬性可透過裝置 transportOptions 中的 motionSensitivity 屬性設定。triggerOptions這些選項是在每個裝置的 PushAvStreamTransportTrait 特徵中定義。

喚醒敏感度只能設為下列值：

1 = 低
5 = 中
10 = 高

更新程序是使用 findTransport 指令找出有效錄製串流的傳輸設定，然後使用 modifyPushTransport 指令，以新的感應度值修改設定。

modifyPushTransport 指令需要傳遞完整的 TransportOptionsStruct，因此您必須先從目前的設定複製現有值。如要瞭解如何產生執行這項操作的輔助函式，請參閱「產生 TransportOptionsStruct」。

func setWakeUpSensitivity(to value: UInt8) async {
  do {
    let connection = try await getRecordingConnection()
    guard let connection,
      let transportOptions = connection.transportOptions
    else {
      // Error - Transport options not available
      return
    }

    guard transportOptions.triggerOptions.motionSensitivity != nil else {
      // Error - Motion sensitivity not available to be updated for this device
      return
    }

    try await pushAvStreamTransportTrait.modifyPushTransport(
      connectionID: connection.connectionID,
      transportOptions: self.getTransportOptions(
        transportOptions: transportOptions,
        wakeUpSensitivity: value,
        maxEventLength: nil
      )
    )

  } catch {
    // Error
  }
}

調整事件錄影時間上限

事件錄影時間上限是指攝影機錄製事件影像片段的時間長度。透過 Home API，您可以為每個裝置設定與透過 Google Home app (GHA) 相同的長度，間隔為秒：

10 秒
15 秒
30 秒
60 秒 (1 分鐘)
120 秒 (2 分鐘)
180 秒 (3 分鐘)

在 Home API 中，這項屬性可透過裝置 transportOptions 中的 motionTimeControl 屬性設定。triggerOptions這些選項是在每個裝置的 PushAvStreamTransportTrait 特徵中定義。

更新程序如下：使用 findTransport 指令找出有效錄製串流的傳輸設定，然後使用 modifyPushTransport 指令，以新的事件長度值修改設定。

func setMaxEventLength(to value: UInt32) async {
  do {
    let connection = try await getRecordingConnection()
    guard let connection,
      let transportOptions = connection.transportOptions
    else {
      // Error - Transport options not available
      return
    }

    guard transportOptions.triggerOptions.motionTimeControl != nil else {
      // Error - Motion time control not available to be updated for this device
      return
    }

    try await pushAvStreamTransportTrait.modifyPushTransport(
      connectionID: connection.connectionID,
      transportOptions: self.getTransportOptions(
        transportOptions: transportOptions,
        wakeUpSensitivity: nil,
        maxEventLength: value
      )
    )

  } catch {
    // Error
  }
}

啟用或停用數據分析

每部裝置都可以個別選擇將詳細的數據分析資料傳送至 Google Home 雲端 (請參閱「適用於 Home API 的 Cloud Monitoring」)。

如要為裝置啟用數據分析功能，請將 ExtendedGeneralDiagnosticsTrait 的 analyticsEnabled 屬性設為 true。當您設定 analyticsEnabled 時，系統會自動將另一個屬性 logUploadEnabled 設為 true，以便將分析記錄檔上傳至 Google Home 雲端。

// Enable analytics
_ = try await extendedGeneralDiagnosticsTrait.update {
  $0.setAnalyticsEnabled(true)
}

// Disable analytics
_ = try await extendedGeneralDiagnosticsTrait.update {
  $0.setAnalyticsEnabled(false)
}

電鈴設定

你可以透過 Home API 控制各種門鈴鈴聲設定。

變更電鈴音效

如要變更門鈴鈴聲，請先使用 ChimeTrait 特徵的 installedChimeSounds 屬性，取得裝置上安裝的鈴聲清單：

doorbellChimeTrait.attributes.installedChimeSounds?.compactMap { chimeSound in
  return chimeSound.chimeID, chimeSound.name
}

然後，使用內建的 setSelectedChime 函式，更新 ChimeTrait 特徵的 selectedChime 屬性：

func setDoorbellChime(chimeID: UInt8) async {
  do {
    _ = try await doorbellChimeTrait.update {
      $0.setSelectedChime(chimeID)
    }
  } catch {
    // Error
  }
}

使用外部電鈴

你可以將門鈴設定為使用外部鈴聲，例如安裝在住家內的機械式電鈴。安裝門鈴時應設定此選項，以免外部電鈴可能損壞。

如要指出安裝的外部電鈴類型，請使用 ExternalChimeType，透過內建的 setExternalChime 函式更新 ChimeTrait 特徵的 externalChime 屬性：

// Indicate the external chime is mechanical
func setExternalChime(to value: Google.ChimeTrait.ExternalChimeType) async {
  do {
    _ = try await doorbellChimeTrait.update {
      $0.setExternalChime(value)
    }
  } catch {
    // Error
  }
}

變更外部電鈴時長

你可以透過 Home API 設定外部電鈴的響鈴時間 (以秒為單位)。如果外部電鈴支援電鈴持續時間，使用者可能需要設定這項功能。

此處設定的值取決於外部電鈴本身的規格，以及建議的電鈴長度。

如要變更外部鈴聲的持續時間，請使用內建的 setExternalChimeDurationSeconds 函式，更新 ChimeTrait 特徵的 externalChimeDurationSeconds 屬性：

// Change the external chime duration
func setExternalChimeDuration(to value: UInt16) async {
  do {
    _ = try await doorbellChimeTrait.update {
      $0.setExternalChimeDuration(value)
    }
  } catch {
    // Error
  }
}

啟用鈴聲主題

部分門鈴可能提供限時鈴聲。例如節慶專屬鈴聲。這些稱為鈴聲主題。

如要查看使用者可用的鈴聲主題，請建立時間範圍篩選器，並使用該篩選器篩選 ChimeThemes 特徵的 getAvailableThemes 指令結果。這會傳回可用主題清單，包括主題名稱。

以下範例說明如何篩選清單。如果目前時間介於主題的開始和結束時間 (分別為 startTimeSeconds 和 endTimeSeconds 值) 之間，系統就會將該主題視為有效。如果未設定開始時間，系統會將其視為從時間開始起就處於有效狀態。如果未設定結束時間，廣告活動會無限期持續放送。如果兩者皆未提供，主題一律會處於啟用狀態。

let chimeThemes = try await chimeThemeTrait.getAvailableThemes().themes

if !chimeThemes.isEmpty {
  var chimeThemeSettings = []
  for chimeTheme in chimeThemes {
    let currentDateTime = UInt64(Date().timeIntervalSince1970)

    // Only show chime themes that are active.
    if chimeTheme.startTimeSeconds ?? 0 &lt;= currentDateTime
      &amp;&amp; chimeTheme.endTimeSeconds ?? UInt64.max &gt;= currentDateTime
    {
      self.chimeThemeSettings.append(chimeTheme.name)
    }
  }
}

取得所需主題的名稱 (例如 Christmas) 後，即可使用 ChimeThemes ChimeThemes 特徵的 setSelectedTimeboxedThemeName() 函式選取該主題。

private func setChimeTheme(to value: String) async throws {
  _ = try await chimeThemeTrait.update {
    $0.setSelectedTimeboxedThemeName(value)
  }
}```