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

iOS 向けドアベルデバイスガイド

ドアホンデバイスタイプは、2 つのトレイトを使用して実装されます: PushAvStreamTransportTraitプッシュベースのプロトコルを使用して音声と動画のストリーム転送を処理します。 WebRtcLiveViewTraitライブストリームとトークバックを制御する機能を提供します。

機能を使用したり、属性を更新したりする前に、必ずデバイスの属性とコマンドのサポートを確認してください。詳しくは、でデバイスを制御する iOSをご覧ください。

Home APIs デバイスタイプトレイト Swift サンプルアプリユースケース

Home APIs デバイスタイプ	トレイト	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]

シリアル番号を取得する

デバイスのシリアル番号を取得するには、 GetSerialNumber コマンドの ExtendedBasicInformation トレイトを使用します。この例では、シリアル番号を serialNumber という名前の変数に保存しています。

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

クイック応答

クイック応答機能を使用すると、ユーザーは事前に定義されたメッセージをドアホンデバイスに送信できます。

この機能は、ドアホンデバイスでのみ使用できます。事前に定義されたメッセージのリストはパートナーアプリで確認でき、ユーザーが選択できるように表示されます。事前に定義されたメッセージはユーザーが編集することはできません。

クイック応答は、PresetMessage トレイトを使用して実装されます。

プリセットメッセージを再生する

プリセットメッセージを再生するには、 availablePhraseTypes プロパティにある文字列値のいずれかを渡して playPresetMessageメソッドを呼び出します。


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

デバイスがクラウドに接続した最新の時刻を取得する

デバイスがクラウドに接続した最新の時刻を確認するには、 lastContactTimestamp 属性を ExtendedGeneralDiagnostics 使用します。

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 アドレスを確認するには、networkInterfaces 属性を使用します。 GeneralDiagnosticsTrait アドレスは 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:) メソッドに送信します。このメソッドは次の 3 つの値を返します。

セッションの 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
  }
}

トークバックを開始 / 停止する

トークバックを開始するには、 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 トレイトに対してクエリを実行し、サポートされているストリームの画質を QualityHint 値（.sd、.hd、.fhd、.qhd、.uhd など）のリストとして公開します。 supportedQualityHints プロパティを使用して。
ライブストリームの画質を変更する: 選択した 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 に基づいて、カメラがオンラインとして表示されることがあります。

ライブ配信にアクセスできず、カメラはクラウドイベントを検出しません。

録画機能が有効になっているかどうかを確認する

カメラの録画機能が有効になっているかどうかを確認するには、接続がアクティブかどうかを確認します。次の例では、これを行うための 2 つの関数を定義しています。

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 APIs を介して制御できます。

バッテリー使用量の設定

エネルギーバランスを設定すると、デバイスのバッテリー駆動時間とパフォーマンスのトレードオフを構成できます。「拡張」、「バランス」、「パフォーマンス」など、さまざまなバッテリープロファイルを作成して切り替えることができます。

この機能は、 currentEnergyBalance 属性を更新することで、EnergyPreference トレイトに実装されます。この属性は、デバイスの 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)
  }
}

バッテリーセーバーを自動的にオンにする

この機能を構成するには、 currentLowPowerModeSensitivity 属性の EnergyPreference トレイトを更新します。この属性はインデックスを使用して感度レベルを選択します。通常、0 は Disabled、1 は Enabled または Automatic を表します。

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

バッテリーの充電状態を取得する

デバイスの現在の充電状態（充電中、フル充電、充電なし）を取得するには、トレイトの batChargeState 属性を使用します。PowerSource

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

バッテリー残量を取得する

現在のバッテリー残量を取得するには、 batChargeLevel 属性の PowerSource トレイトを使用します。レベルは 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"
}

電源を取得する

デバイスが使用している電源を確認するには、 BatPresent 属性と wiredPresent 属性を PowerSource トレイトで使用します。

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

音声設定

さまざまな音声設定は、Home APIs を介して制御できます。

マイクのオンとオフを切り替える

デバイスのマイクのオンとオフを切り替えるには、組み込みの 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 を提供します。

アクティビティエリアを確認する

アクティビティエリアを表示するには、 zones トレイトの ZoneManagement属性を確認します。

let zoneManagementTrait: Google.ZoneManagementTrait

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

アクティビティエリアを追加する

新しいエリアを作成するには、 createTwoDCartesianZone コマンドを使用します。このコマンドは、TwoDCartesianZoneStruct、エリアの名前、頂点、色、使用状況を定義するを受け取ります。

次の例は、4 つの頂点を持つ「Front Porch」という名前のエリアを作成し、サーモン色（#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
}

アクティビティエリアを削除する

エリアを削除するには、特定の zoneId を指定して removeZone コマンドを使用します。

let zoneManagementTrait: Google.ZoneManagementTrait
let zoneID: UInt16

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

サウンドアクティビティトリガー

AvStreamAnalysis トレイトは、カメラとドアホンデバイスのアクティビティ検出トリガーを管理するためのインターフェースを提供します。ビジョンベースのトリガー（人物や車両など）はエリア固有にできますが、サウンド関連のトリガーは通常、デバイスレベルの構成です。

` EventTriggerTypeEnum` を使用したサウンド検知には、次のトリガータイプを使用できます。

モード	列挙値	説明
サウンド	`Sound`	一般的なサウンド検知。
話し声	`PersonTalking`	音声を検出します。
犬の鳴き声	`DogBark`	犬の鳴き声を検出します。
ガラスの割れる音	`GlassBreak`	ガラスの割れる音を検出します。
煙警報	`SmokeAlarm`	煙警報を検出します。多くの場合、T3 の音声パターン（短いビープ音が 3 回鳴った後に一時停止）で認識されます。
一酸化炭素警報	`CoAlarm`	一酸化炭素（CO）警報を検出します。通常、T4 の音声パターン（短いビープ音が 4 回鳴った後に一時停止）で認識されます。

サウンド検知のステータスを確認する

サウンド検知の現在の状態をユーザーに表示するには、デバイスがサポートしている機能と、デバイスのハードウェアで有効になっている機能を確認する必要があります。確認する 2 つの属性は次のとおりです。

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`	動画は 24 時間 365 日録画されます。定期購入が必要です（例: Google Home Premium。
EBR （アクティビティ検出時の録画）	`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 APIs を介して制御できます。

ナイトビジョン機能をオンまたはオフにする

カメラのナイトビジョン機能をオンまたはオフにするには、TriStateAutoEnum を使用して nightVision 属性をCameraAvStreamManagementTraitトレイトの組み込みの 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 の明るさを変更するには、組み込みの setStatusLightBrightness 関数を使用して、CameraAvStreamManagementTrait トレイトの statusLightBrightness 属性を ThreeLevelAutoEnum で更新します。

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

カメラのビューポートを変更する

カメラのビューポートは、 Google Nest カメラの動画でズーム機能や補正機能を使用するサポート記事で説明されているズームと切り抜き機能と同じです。

ビューポートは、ビューポートの座標として使用される 4 つの値を含む ViewportStruct で定義されます。座標は次のように定義されます。

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

ViewportStruct の値を決定する方法は、アプリの UI とカメラの実装によって異なります。基本的なレベルでは、カメラの動画のビューポートを設定するには、 viewport トレイトの CameraAvStreamManagementTrait 属性を ViewportStruct で更新します。組み込みの setViewport 関数を使用します。

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 クラウドに送信するかどうかを個別に選択できます（Home APIs の Cloud Monitoring をご覧ください）。

デバイスの分析を有効にするには、 analyticsEnabled) の ExtendedGeneralDiagnosticsTrait を 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
)

帯域幅の品質を決定する

videoStreamId プロパティは、TransportOptionsStructに対応します。

サポートされている動画ストリームを取得するには、 allocatedVideoStreams 属性を参照してください。これは、VideoStreamStructs のリストです。デバイスの CameraAvStreamManagement トレイトから。

デバイスの復帰感度を調整する

motionSensitivity プロパティは、TransportTriggerOptionsStruct の次の値に対応します。

ラベル	値（UInt8）
低	1
メディア	5
高	10

最長アクティビティ時間を調整する

maxDuration の TransportMotionTriggerTimeControlStruct プロパティは、次の UInt32 の長さ（秒単位）に対応します。

10、15、30、60、120、180

チャイムの設定

さまざまなドアホンチャイムの設定は、Home APIs を介して制御できます。

チャイム音を変更する

ドアホンチャイム音を変更するには、まずデバイスにインストールされているチャイム音のリストを取得します。これには、 installedChimeSounds 属性をChimeTraitトレイトで使用します。

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関数で externalChime 属性のChimeTraitトレイトを更新します。

// 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 APIs を介して構成できます。外部チャイムがチャイムの長さをサポートしている場合は、ユーザーがこれを構成できます。

ここで設定する値は、外部チャイム自体の仕様と、推奨されるチャイムの長さによって異なります。

外部チャイムの長さを変更するには、組み込みの setExternalChimeDurationSeconds 関数を使用して、ChimeTrait トレイトの externalChimeDurationSeconds 属性を更新します。

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

チャイムのテーマを有効にする

一部のドアホンには、期間限定でユーザーが利用できるチャイムがあります。たとえば、祝日固有のチャイムなどです。これらはチャイムのテーマと呼ばれます。

ユーザーが利用できるチャイムのテーマを確認するには、タイムボックスフィルタを作成し、それを使用して getAvailableThemes コマンドの結果をフィルタします。 ChimeThemes トレイト。これにより、テーマ名など、利用可能なテーマのリストが返されます。

次の例は、リストをフィルタする方法を示しています。現在の時刻が開始時刻と終了時刻（それぞれ 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 APIs の VisitorAnnouncement トレイトを使用して、ドアホンの訪問客の通知設定をクエリして管理できます。このトレイトは、誰かがドアホンを鳴らしたときに、Google スマートスピーカーまたはディスプレイで訪問客の存在を通知するかどうかを制御します。

次の例は、訪問客の通知が有効になっているかどうかを確認する方法と、この設定を更新する方法を示しています。

let visitorAnnouncementsEnabled: Bool = visitorAnnouncementTrait.attributes.visitorAnnouncementsEnabled

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

iOS 向けドアベル デバイスガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

デバイスに関する基本情報を取得する

シリアル番号を取得する

クイック応答

プリセット メッセージを再生する

音声言語を設定する

音声言語を設定する

デバイスがクラウドに接続した最新の時刻を取得する

カメラのマウントタイプの設定

デバイスの接続を確認する

デバイスの IP アドレスを取得する

ライブ配信を開始する

ライブ配信を延長する

トークバックを開始 / 停止する

ライブ配信を管理する

録画機能を有効または無効にする

録画機能が有効になっているかどうかを確認する

バッテリーの設定

バッテリー使用量の設定

バッテリー セーバーを自動的にオンにする

バッテリーの充電状態を取得する

バッテリー残量を取得する

電源を取得する

音声設定

マイクのオンとオフを切り替える

音声録音のオンとオフを切り替える

スピーカーの音量を調整する

アクティビティ エリアの設定

アクティビティ エリアを確認する

アクティビティ エリアを追加する

アクティビティ エリアを更新する

アクティビティ エリアを削除する

サウンド アクティビティ トリガー

サウンド検知のステータスを確認する

有効なトリガーのセットを更新する

録画モード

録画モードを確認する

録画モードを変更する

その他の設定

ナイトビジョン機能をオンまたはオフにする

ステータス LED の明るさを変更する

カメラのビューポートを変更する

TransportOptionsStruct を生成する

分析を有効または無効にする

転送と録画の構成

転送設定を読み取る

転送設定を更新する

帯域幅の品質を決定する

デバイスの復帰感度を調整する

最長アクティビティ時間を調整する

チャイムの設定

チャイム音を変更する

外部チャイムを使用する

外部チャイムの長さを変更する

チャイムのテーマを有効にする

訪問客の通知の設定

iOS 向けドアベルデバイスガイド

プリセットメッセージを再生する

バッテリーセーバーを自動的にオンにする

アクティビティエリアの設定

アクティビティエリアを確認する

アクティビティエリアを追加する

アクティビティエリアを更新する

アクティビティエリアを削除する

サウンドアクティビティトリガー