Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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!
// [END get_device_information]

取得序號

如要取得裝置序號，請使用 ExtendedBasicInformation 特徵的 GetSerialNumber 指令。這個範例顯示如何將序號儲存在名為 serialNumber 的變數中：

// Assuming extendedBasicInformationTrait: Google.ExtendedBasicInformationTrait
let response = try await extendedBasicInformationTrait.getSerialNumber()
let serialNumber = response.serialNumber

應答短訊

使用者可以透過應答短訊功能，將預先定義的訊息傳送至門鈴裝置。

這項功能僅適用於門鈴裝置。合作夥伴應用程式可存取預先定義的訊息清單，並向使用者顯示這些訊息供選擇。預先定義的訊息無法由使用者編輯。

應答短訊功能是透過 PresetMessage 特徵實作。

播放預設訊息

如要播放預設訊息，請呼叫 playPresetMessage 方法，並傳遞 availablePhraseTypes 屬性中的其中一個字串值。


import GoogleHomeSDK
import GoogleHomeTypes

func playDoorbellPresetMessage(device: HomeDevice, phraseTypeString: String) async {
    // 1. Retrieve the GoogleDoorbellDeviceType helper on the device
    guard let doorbellDeviceType = await device.types.get(GoogleDoorbellDeviceType.self) else {
        print("This device is not a Google Doorbell or is currently uninitialized.")
        return
    }

    // 2. Extract the Google.PresetMessageTrait
    guard let presetMessageTrait = doorbellDeviceType.traits[Google.PresetMessageTrait.self] else {
        print("PresetMessageTrait is not supported on this device.")
        return
    }

    // 3. (Optional) Check available phrase types supported by the device
    if let availablePhrases = presetMessageTrait.attributes.availablePhraseTypes {
        let phraseTypeNames = availablePhrases.map { $0.phraseType }
        print("Supported quick response phrases: \(phraseTypeNames)")
    }

    // 4. Send the playPresetMessage command asynchronously
    do {
        try await presetMessageTrait.playPresetMessage(phraseType: phraseTypeString)
        print("Preset message successfully requested.")
    } catch {
        print("SDK error occurred playing preset message: \(error)")
    }
}

設定使用的語言

使用 LocalizationConfiguration 特徵的 setActiveLocale 方法，將裝置的有效口語語言設為特定語言代碼 (例如「en_US」)。

// Setting the active language
// Assuming localizationConfigurationTrait: Matter.LocalizationConfigurationTrait
let selectedLocale = "en_US"
try await localizationConfigurationTrait.update {
    $0.setActiveLocale(selectedLocale)
}

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

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

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

攝影機支架類型設定

Mount 特徵包含攝影機支架設定和狀態資訊。您可以讀取掛接狀態、偵測類型和掛接類型名稱等屬性。此外，您可以使用 Mount 特徵覆寫預設的掛接類型設定。

// 1. Get the Mount trait
guard let mountTrait = deviceType.traits[Google.MountTrait.self] else {
  print("Mount trait not supported or configured on this device.")
  return
}

// 2. Read the current mount state, detection type, and type name
let mountState         = mountTrait.attributes.mountState         // Type: Google.MountTrait.MountStateEnum?
let mountDetectionType = mountTrait.attributes.mountDetectionType // Type: Google.MountTrait.MountDetectionTypeEnum?
let mountTypeName      = mountTrait.attributes.mountTypeName      // Type: String?

// 3. Update the mount type override
try await mountTrait.update { mutableTrait in
  mutableTrait.setMountTypeOverride(.official)
}

檢查裝置的連線狀態

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

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

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

取得裝置的 IP 位址

如要找出裝置的 IP 位址，請使用 GeneralDiagnosticsTrait 的 networkInterfaces 屬性。位址會以 Data 物件的形式傳回，您可以使用 Network 架構將位址格式化為標準 IPv4 或 IPv6 字串：

func getIpAddresses(trait: Matter.GeneralDiagnosticsTrait) -> [String] {
  let interfaces = trait.attributes.networkInterfaces ?? []
  var ipAddresses: [String] = []

  for interface in interfaces {
    for data in interface.iPv4Addresses {
      if let ipv4 = IPv4Address(data) {
        ipAddresses.append(String(describing: ipv4))
      }
    }
    for data in interface.iPv6Addresses {
      if let ipv6 = IPv6Address(data) {
        ipAddresses.append(String(describing: ipv6))
      }
    }
  }

  return ipAddresses
}

開始直播

如要開始直播，請將工作階段描述通訊協定 (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)")
  }
}

管理直播

調整直播品質有助於根據用戶的觀看環境 (例如在顯示較小的預覽圖塊、格狀檢視畫面或子母畫面模式時切換至較低解析度)，最佳化頻寬用量。

使用 WebRtcLiveView 特徵動態變更畫質，可專門管理特定用戶端上現正進行的直播工作階段解析度。這與直接在裝置上設定裝置的頻寬用量設定不同，後者會影響所有同時觀看者，以及儲存至雲端的過往錄影品質。

以下範例說明如何擷取及更新裝置的直播品質：

擷取支援的畫質選項：取得裝置支援的可用串流解析度。程式碼會查詢 WebRtcLiveView 特徵，並使用 supportedQualityHints 屬性，將支援的串流品質公開為 QualityHint 值清單 (例如 .sd、.hd、.fhd、.qhd 或 .uhd)。
變更直播畫質：套用所選 QualityHint 變更目前直播的串流解析度 (例如從標準畫質切換為高畫質)。updateQualityHint 函式會使用 WebRtcLiveView 特徵的 changeLiveViewQuality 方法，將所選的 QualityHint 設定套用至有效媒體工作階段。

public var supportedQualityHints: [Google.WebRtcLiveViewTrait.QualityHint] {
  return liveViewTrait?.attributes.supportedQualityHints ?? []
}

public func updateQualityHint(
  liveViewTrait: Google.WebRtcLiveViewTrait,
  hint: Google.WebRtcLiveViewTrait.QualityHint,
  mediaSessionId: String
) async {
  do {
    _ = try await liveViewTrait.changeLiveViewQuality(
      mediaSessionId: mediaSessionId,
      qualityHint: hint
    )
  } catch {
    // 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`	偵測一氧化碳警報，通常會發出 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 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 透過內建的 setNightVision 函式更新 CameraAvStreamManagementTrait 特徵的 nightVision 屬性：

// 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
}

啟用或停用數據分析

每部裝置都可以個別選擇是否要將詳細的數據分析資料傳送至 Google Home 雲端 (請參閱「Google 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)
}

傳輸和錄製設定

本節說明攝影機串流品質和事件觸發相關設定。這些設定由 PushAvStreamTransport 特徵管理。

讀取傳輸設定

本節說明如何從攝影機或門鈴裝置擷取目前的設定。這項服務會擷取 PushAvStreamTransport 特徵、找出用於錄製的特定連線，然後擷取頻寬品質、喚醒靈敏度和最長事件長度的目前值。

// Assuming access to
// var pushAvStreamTransportTrait: Google.PushAvStreamTransportTrait
let connections = try await pushAvStreamTransportTrait.findTransport().transportConfigurations

// Locate the connection designated for recording
let recordingConnection = connections.first { connection in
    guard let transportOptions = connection.transportOptions else { return false }
    return transportOptions.streamUsage == .recording
}

let options = recordingConnection?.transportOptions

// 1. Bandwidth Quality (Video Stream ID)
let videoStreamId = options?.videoStreamID

// 2. Wake-up Sensitivity (Motion Sensitivity)
let wakeUpSensitivity = options?.triggerOptions.motionSensitivity

// 3. Max Event Length (Motion Trigger Time Control)
let maxEventLength = options?.triggerOptions.motionTimeControl?.maxDuration

更新傳輸設定

本節說明如何變更傳輸設定。這會建立新的 TransportOptionsStruct，其中包含新值，然後使用 modifyPushTransport 指令將這些更新的設定傳回裝置，並套用至上一個步驟中找到的錄製連線。

如要修改這些設定，請使用 modifyPushTransport 指令搭配 TransportOptionsStruct。

// Example: Updating to Max Quality and 30s duration
let currentOptions = recordingConnection!.transportOptions!
let newOptions = Google.PushAvStreamTransportTrait.TransportOptionsStruct(
    streamUsage: .recording,
    videoStreamID: 2, // Max Quality
    tlsEndpointID: currentOptions.tlsEndpointID,
    url: currentOptions.url,
    triggerOptions: Google.PushAvStreamTransportTrait.TransportTriggerOptionsStruct(
        triggerType: .motion,
        motionSensitivity: 5, // Medium
        motionTimeControl: Google.PushAvStreamTransportTrait.TransportMotionTriggerTimeControlStruct(
            initialDuration: currentOptions.triggerOptions.motionTimeControl?.initialDuration ?? 10,
            augmentationDuration: currentOptions.triggerOptions.motionTimeControl?.augmentationDuration ?? 5,
            maxDuration: 30,
            blindDuration: currentOptions.triggerOptions.motionTimeControl?.blindDuration ?? 0
        )
    ),
    ingestMethod: currentOptions.ingestMethod,
    containerOptions: currentOptions.containerOptions
)

try await pushAvStreamTransportTrait.modifyPushTransport(
    connectionID: recordingConnection!.connectionID,
    transportOptions: newOptions
)

判斷頻寬品質

TransportOptionsStruct 的 videoStreamId 屬性會對應至特定影片串流設定。

如要取得支援的影片串流，請參閱 allocatedVideoStreams 屬性，這是 VideoStreamStructs 的清單。裝置的 CameraAvStreamManagement 特徵。

調整裝置的喚醒靈敏度

TransportTriggerOptionsStruct 的 motionSensitivity 屬性對應下列值：

標籤	值 (UInt8)
低	1
中	5
高	10

調整事件錄影時間上限

TransportMotionTriggerTimeControlStruct 的 maxDuration 屬性會對應至下列 UInt32 時間長度 (以秒為單位)：

10、15、30、60、120、180

電鈴設定

你可以透過 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 更新 ChimeTrait 特徵的 externalChime 屬性，方法是使用內建的 setExternalChime 函式：

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

變更外部電鈴時長

你可以透過 Google 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)
  }
}

訪客通報設定

你可以使用 Home API 的 VisitorAnnouncement 特徵，查詢及管理門鈴的訪客通報設定。這項特徵可控制有人按門鈴時，是否要在 Google 智慧音箱或螢幕上通報訪客。

以下範例說明如何檢查訪客通報是否已啟用，以及如何更新這項設定：

let visitorAnnouncementsEnabled: Bool = visitorAnnouncementTrait.attributes.visitorAnnouncementsEnabled

let value: Bool
_ = try await self.visitorAnnouncementTrait?.update {
  $0.setVisitorAnnouncementsEnabled(value)
}

iOS 裝置適用的門鈴裝置指南 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

取得裝置的基本資訊

取得序號

應答短訊

播放預設訊息

設定使用的語言

設定使用的語言

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

攝影機支架類型設定

檢查裝置的連線狀態

取得裝置的 IP 位址

開始直播

延長直播時間

啟動及停止 TalkBack

管理直播

啟用及停用錄製功能

確認是否已啟用錄製功能

電池設定

設定電池用量偏好設定

開啟自動省電模式

取得電池充電狀態

取得電池電量

取得電源

音訊設定

開啟或關閉麥克風

開啟或關閉音訊錄音功能

調整音箱音量

活動區設定

查看活動區

新增活動區

更新活動區

刪除活動區

聲響偵測事件觸發條件

查看聲響偵測狀態

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

錄製模式

檢查錄製模式

變更錄製模式

其他設定

開啟或關閉夜視模式

變更狀態 LED 燈的亮度

變更攝影機可視區域

產生 TransportOptionsStruct

啟用或停用數據分析

傳輸和錄製設定

讀取傳輸設定

更新傳輸設定

判斷頻寬品質

調整裝置的喚醒靈敏度

調整事件錄影時間上限

電鈴設定

變更鈴聲

使用外部電鈴

變更外部電鈴時長

啟用鈴聲主題

訪客通報設定

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