iOS'te Home API'lerini kullanarak mobil uygulama oluşturma

1. Giriş

Home API'leri nelerdir?

Google Home API'leri, geliştiricilerin Google Home ekosisteminden yararlanabileceği bir dizi kitaplık sunar. Geliştiriciler, Home API'leri ile akıllı ev cihazlarını sorunsuz bir şekilde devreye alan ve kontrol eden uygulamalar oluşturabilir.

Bu videoda, oluşturacağınız mobil uygulamanın kısa bir tanıtımı yapılmaktadır. Bu nedenle, codelab'i yaparken videoyu takip edin.

Home API'lerinin bileşenleri

Home API'leri şunlardan oluşur:

• Device (Cihaz) ve Structure (Yapı) API'leri: Kullanıcının eviyle etkileşimde bulunma. Uygulamalar, cihazlar, odalar ve yapılarla ilgili bilgileri okumak (ör. mevcut termostat sıcaklığını görme) ve cihazları kontrol etmek (ör. termostatın istenen sıcaklık ayarını değiştirme) için bu API'leri kullanabilir.
• Commissioning API: Yeni Matter cihazlarını en az çabayla kumaşa devreye alın (kurun).
• Otomasyon API'si: Kullanıcının evinde çalışan otomasyonları oluşturun, silin ve sorgulayın.

Ön koşullar

• Xcode'un en son kararlı sürümü.
• Evde en az bir yapıya sahip bir Google Hesabı
• Test hesabı ile ayarlanmış, iOS 16.4 veya sonraki sürümlerin yüklü olduğu bir iOS cihaz.
• Sağlama profilini oluşturmak için Apple Developer Programı'na kayıtlı bir Apple Kimliği.
• Home API'lerini destekleyen bir Google hub'ı.

Neler öğreneceksiniz?

• En iyi uygulamalarla Home API'lerini kullanarak iOS uygulaması oluşturma
• Akıllı bir evi temsil etmek ve kontrol etmek için Cihaz ve Yapı API'lerini kullanma
• Cihazları Google Home ekosistemine eklemek için Commissioning API'yi kullanma
• Temel bir otomasyon oluşturmak için Automation API'yi kullanma

2. Evinizi kurma

Cihazları hazırlama

Google Home Playground, önceden oluşturulmuş çeşitli akıllı ev cihazları sunar. Özellikle evinizde sınırlı sayıda cihaz varsa Home API'lerinin tüm potansiyelini keşfetmek için bu platformu kullanmanız önerilir.

Google Home Playground'da oturum açma ve Google Home uygulamasında hesap bağlama işlemini tamamlama talimatlarını uygulayın. Bu işlemi tamamladıktan sonra cihazları Google Home uygulamasındaki "Cihazlar" sekmesinde görebilirsiniz.

3. Hazırlanma

Örnek uygulamanın kodunu alma

GitHub'dan kaynak kodu kopyalayarak başlayın:

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

Örnek dizin, bu codelab için start ve finished olmak üzere iki dal içerir.

• start: Bu proje için başlangıç kodu. Codelab'i tamamlamak üzere bu kodda değişiklik yapacaksınız.
• finished: Çalışmanızı kontrol etmek için kullanılan bu codelab'in tamamlanmış kodu.

"Başlangıç" kodunu keşfetme

Bu codelab'e, klonlanmış deponuzun start dalına geçerek başlayın:

git checkout start

Bu dal, projenin başlangıç kodunu içerir. Bu kodu, codelab boyunca tam işlevselliği uygulamak için değiştireceksiniz. Codelab örnek uygulaması, Home APIs iOS SDK ile etkileşim kurmak için Swift'te oluşturulmuş temel bir yapı sunar. start projesindeki temel bileşenlere hızlıca göz atalım:

• Main Entry (GoogleHomeAPISampleIOSApp): GoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift konumunda bulunan bu uygulama, ana uygulama giriş noktasıdır. SDK'yı yapılandırıp başlatır ve birincil kullanıcı arayüzünü ayarlar.
• Core Views (View/):
  • MainView.swift: Lansmandan sonraki kök görünüm. Ana NavigationView'yi içerir. Etkin Google Home yapısını seçer ve ilgili StructureView simgesini gösterir.
  • StructureView.swift: Cihazlar ızgarası ile Otomasyonlar listesi arasında geçiş yapmak için sekmeleri kullanarak, şu anda seçili yapının içeriğini gösterir. Ayrıca oda veya cihaz eklemek için menüler de sunar.
  • DeviceView.swift: StructureView ızgarasındaki tek bir cihazın etkileşimli kutusunu gösterir.
  • AutomationsView.swift: Yapı için mevcut otomasyonların listesini gösterir ve otomasyon ayrıntılarını oluşturmak veya görüntülemek için gezinme olanağı sağlar.
• ViewModels (ViewModel/): Bu sınıflar, görünümlerin durumunu ve mantığını yönetir.
  • AccountViewModel.swift: Home nesnesine bağlantıyı işler ve kimlik doğrulama durumunu yönetir.
  • MainViewModel.swift: Kullanılabilir Structure nesnelerinin listesini yönetir ve seçilen yapıyı takip eder.
  • StructureViewModel.swift: Seçilen yapıdaki odaların ve DeviceControl nesnelerinin gösterimini yönetir.
  • AutomationList.swift, AutomationViewModel.swift vb.: Otomasyonların getirilmesi, gösterilmesi, oluşturulması ve yönetilmesi işlemlerini gerçekleştirir.
• Device Controls (ViewModel/Device/):
  • DeviceControl.swift: Kullanıcı arayüzünde kontrol edilebilir cihazları temsil eden bir temel sınıf.
  • Belirli alt sınıflar (LightControl.swift, FanControl.swift, OnOffPlugInUnitControl.swift vb.): Farklı cihaz türleri için özelliklerine göre kullanıcı arayüzü mantığını, cihaz kontrolünü ve durum eşlemeyi uygulayın.
  • DeviceControlFactory.swift: Belirli bir HomeDevice için uygun DeviceControl alt sınıfını oluşturmaktan sorumludur.
• Commissioning (Commissioning/):
  • CommissioningManager.swift: Matter cihazı devreye alma akışını yönetme mantığını içerir.
• Utilities & UX (Utils/, UX/, Storage/): Kullanıcı arayüzü öğeleri (renkler, boyutlar), hata işleme, veri depolama (SelectedStructureStorage.swift) ve diğer yardımcı programlar için yardımcı kod içerir.

Bu codelab boyunca, TODO gibi yorumlar veya start projesinde yorum satırına alınmış kod blokları ve uyarılar göreceksiniz. Bunlar, sağlanan adımları izleyerek gerekli işlevleri uygulamak için kod ekleyeceğiniz veya yorumdan çıkaracağınız bölümleri işaretler.

Apple dağıtım yapılandırma dosyaları oluşturma

App Attest'i yapılandırmak için Apple dağıtım yapılandırma dosyaları oluşturma talimatlarını uygulayın. Kurulumdan sonra uygulamanın yalnızca gerçek bir cihaza dağıtılabileceğini, simülatöre dağıtılamayacağını unutmayın.

Kimlik doğrulama ayarlama

OAuth istemci kimliğini almak ve Home API'lerini etkinleştirmek için önce Google Cloud'da oturum açın ve yeni bir proje oluşturun veya mevcut bir projeyi seçin. Ardından, OAuth istemci kimliğini oluşturma ve Home API'lerini etkinleştirme ile ilgili adımları uygulayın ve hesabınızı izin verilenler listesine ekleyin.

SDK'yı ayarlama

Home APIs iOS SDK'sını edinin ve SDK'yı ayarlama bölümünde verilen kurulum talimatlarına bakarak yapılandırın. HOME_API_TODO_ADD_APP_GROUP değerini kendi uygulama grubunuzla değiştirmeyi unutmayın.

Projeyi oluşturma ve çalıştırma

Projeyi start dalıyla oluşturup çalıştırdıktan sonra TODO iletişim kutusu ve "Oturum açmanız gerekiyor" mesajını gösteren bir ekran görünmelidir. Home API'leri ile etkileşim, aşağıdaki bölümlerde uygulanacaktır.

Not: Projede iletişim kutusunda gösterilen metni arayarak değiştirilmesi gereken kodu bulun. Örneğin, "YAPILACAKLAR: Evi başlat" ifadesini arayın.

4. Başlatma

Evi ilk kullanıma hazırlama

iOS için Home API'lerinden herhangi birini kullanmadan önce uygulamanızda Home başlatmanız gerekir. Home, SDK'ya üst düzey giriş noktasıdır ve kullanıcının yapısındaki tüm öğelere erişim sağlar. Belirli bir türdeki tüm öğeler istendiğinde API, sonuçları nasıl alacağınızı seçmenize olanak tanıyan bir Query nesnesi döndürür. GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift bölümünde, ana sayfa başlatma işlemini uygulamak için connect() bölümündeki yorumu ve uyarıyı kaldırın.

  /// TODO: initialize Home
  /// Remove comments to initialize Home and handling permission.
  private func connect() {
    Task {
      do {
        self.home = try await Home.connect()
      } catch {
        Logger().error("Auth error: \(error).")
      }
    }
  }

Home API'lerini kullanma izni

Uygulamayı çalıştırdığınızda izin ekranı görünür. Google Home yapısını seçin ve Google Cloud projenizin izin verilenler listesinde bulunan hesabı seçin.

5. Cihazlar ve Yapılar

Odaları ve cihazları alma

GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift içinde, seçilen yapıdaki odaları ve cihazları sırasıyla home.rooms() ve home.devices() ile almak için getRoomsAndDevices() içindeki yorumu ve uyarıyı kaldırın.

  /// TODO: get rooms and devices
  /// Remove comments to get the rooms and devices from home entry
  private func getRoomsAndDevices(){
    self.home.rooms().batched()
      .combineLatest(self.home.devices().batched())
      .receive(on: DispatchQueue.main)
      .catch { error in
        Logger().error("Failed to load rooms and devices: \(error)")
        return Just((Set<Room>(), Set<HomeDevice>()))
      }
      .map { [weak self] rooms, devices in
        guard let self = self else { return [] }
        self.hasLoaded = true
        return self.process(rooms: rooms, devices: devices)
      }
      /// receive from .map and .assign() to publisher entries
      .assign(to: &self.$entries)
  }

process() işlevi, DeviceControl ve DeviceControlFactory kullanılarak cihazların HomeDevices olarak etkileşimde bulunmasını sağlamadan önce cihazların aynı odada olduğundan emin olur.

Not: Cihazınız DeviceControlFactory listesinde yer almıyorsa "Desteklenmiyor" olarak gösterilir. Hangi cihazların desteklendiği hakkında daha fazla bilgi edinmek için iOS'te Desteklenen Cihaz Türleri sayfasına bakın.

Cihazlarla etkileşim kurma

Cihazlarda dokunulduğunda veya kaydırıldığında eklenti outlet1 başlangıçta devre dışıdır. Bu öğeyle etkileşimi etkinleştirmek için GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift simgesini bulun ve primaryAction() işlevindeki yorumu ve uyarıyı kaldırın.

  /// TODO: primary action of OnOffPlug
  /// Toggles the plug; usually provided as the `action` callback on a Button.
  public override func primaryAction() {
    self.updateTileInfo(isBusy: true)
    Task { @MainActor [weak self] in
      guard
        let self = self,
        let onOffPluginUnitDeviceType = self.onOffPluginUnitDeviceType,
        let onOffTrait = onOffPluginUnitDeviceType.matterTraits.onOffTrait
      else { return }

      do {
        try await onOffTrait.toggle()
      } catch {
        Logger().error("Failed to to toggle OnOffPluginUnit on/off trait: \(error)")
        self.updateTileInfo(isBusy: false)
      }
    }
  }

OnOffPlugInUnitControl sınıfında bulunan primaryAction() işlevi, akıllı prizin veya OnOffPluginUnitDeviceType ile temsil edilen herhangi bir cihazın açık/kapalı durumunu değiştirir.

Ek cihaz kontrolü örneklerini GoogleHomeAPISampleIOS/ViewModel/Device adresinde bulabilirsiniz.

Yeni oda oluşturma

Structure API, odaların oluşturulmasına ve silinmesine, ayrıca cihazların odalar arasında aktarılmasına olanak tanır.

GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift bölümünde yorumu ve addRoom() bölümünde uyarıyı kaldırın.

  /// TODO: add room
  /// Add a new room in a given structure.
  func addRoom(name: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.createRoom(name: name)
      } catch {
        Logger().error("Failed to create room: \(error)")
      }
    }
  }

structure.createRoom() ile yeni bir oda oluşturmak için sol üst köşeye gidin ve "+" simgesi > Oda Ekle'yi seçin. Yeni oda adınızı girin ve "Oda Oluştur"u tıklayın. Yeni oda birkaç saniye sonra görünür.

Cihazı farklı bir odaya taşıma

GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift bölümünde yorumu ve moveDevice() bölümünde uyarıyı kaldırın.

  /// TODO: move device
  /// Move a device into a different room.
  func moveDevice(device deviceID: String, to roomID: String, structure: Structure) {
    Task {
      do {
        _ = try await structure.move(device: deviceID, to: roomID)
      } catch {
        Logger().error("Failed to move to room: \(error)")
      }
    }
  }

structure.move() simgesini kullanarak cihazı başka bir odaya taşımak için simgeye uzun basın, "Başka bir odaya taşı"yı seçin ve yeni odayı belirleyin.

Boş bir odayı silme

GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift bölümünde yorumu ve removeRoom() bölümünde uyarıyı kaldırın.

  /// TODO: delete room
  /// Delete an empty room in a given structure.
  func removeRoom(id: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.deleteRoom(id: id)
      } catch {
        Logger().error("Failed to remove room: \(error)")
      }
    }
  }

structure.deleteRoom() ile boş bir odayı silmek için oda adının sağındaki çöp kutusu simgesini tıklayın ve işlemi onaylayın. Yalnızca boş odaların silinebileceğini unutmayın.

Not: Boş bir oda oluşturmak için cihazı geri hareket ettirin.

6. Kurulum

Not: Bu bölüm için Google hub ve Matter cihazı gerekir. Yapınızdaki Google hub'ının internete bağlı ve erişilebilir olduğundan emin olun. Matter cihazınız yoksa bunun yerine Matter Virtual Device uygulamasını kullanmayı deneyin.

Matter cihazı ekleme

Commissioning API, uygulamanızın kullanıcının evine ve Google Hesabı'na yeni Matter cihazları eklemesini sağlar. Bu sayede, doğrudan uygulamanızda sorunsuz bir kurulum deneyimi sunulur.

GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift bölümünde yorumu ve addMatterDevice() bölümünde uyarıyı kaldırın.

  /// TODO: add Matter Device
  /// Starts the Matter device commissioning flow to add the device to the user's home.
  /// - Parameters:
  ///   - structure: The structure to add the device to.
  ///   - add3PFabricFirst: Whether to add the device to a third party fabric first.
  public func addMatterDevice(to structure: Structure, add3PFabricFirst: Bool) {
    self.isCommissioning = true

    /// pass if it's 1p or 3p commissioning
    let userDefaults = UserDefaults(
      suiteName: CommissioningManager.appGroup)
    userDefaults?.set(
    add3PFabricFirst, forKey: CommissioningUserDefaultsKeys.shouldPerform3PFabricCommissioning)

    Task {
      do {
        try await structure.prepareForMatterCommissioning()
      } catch {
        Logger().error("Failed to prepare for Matter Commissioning: \(error).")
        self.isCommissioning = false
        return
      }

      // Prepare the Matter request by providing the ecosystem name and home to be added to.
      let topology = MatterAddDeviceRequest.Topology(
        ecosystemName: "Google Home",
        homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
      )
      let request = MatterAddDeviceRequest(topology: topology)

      do {
        Logger().info("Starting MatterAddDeviceRequest.")
        try await request.perform()
        Logger().info("Completed MatterAddDeviceRequest.")
        let commissionedDeviceIDs = try structure.completeMatterCommissioning()
        Logger().info("Commissioned device IDs: \(commissionedDeviceIDs).")
      } catch let error {
        structure.cancelMatterCommissioning()
        Logger().error("Failed to complete MatterAddDeviceRequest: \(error).")
      }

      self.isCommissioning = false
    }
  }

structure.prepareForMatterCommissioning() ile yeni bir oda oluşturmak için sol üst köşeye gidin ve "+" simgesi > Cihazı Google Fabric'e Ekle'yi seçin. Matter cihazını odanıza eklemek için MatterAddDeviceRequest kullanılır. Oda ve cihaz adı seçildikten sonra cihaz, "Cihazlar" ekranında gösterilir.

7. Otomasyon

Yapıdaki tüm otomasyonları görüntüleme

Alttaki gezinme çubuğunda Otomasyonlar'a dokunun. Bu işlem, yapınızdaki tüm otomasyonları structure.listAutomations() ile listeler.

Not: Ev otomasyonu ayarlamadıysanız "Başlamak için otomasyon ekleyin" mesajını görürsünüz.

Otomasyon oluşturma

Cihaz ve Yapı API'leri ile yeni cihaz ekleme hakkında bilgi sahibi olduğunuza göre artık Otomasyon API'sini kullanarak yeni bir otomasyon oluşturabilirsiniz.

GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift bölümünde yorumu, uyarıyı ve lightAutomation() bölümündeki boş otomasyonu kaldırın.

  /// TODO: create automation
  /// - Parameter devices: devices in current selected structure
  /// - Returns: the automation object to be created
  /// This automation will turn off the light after 5 seconds.
  public func lightAutomation(devices: Set<HomeDevice>) async throws -> any DraftAutomation {
    let light = devices.first { $0.name == "light2" }
    
    guard let light else {
      Logger().error("Unable to find light device with name light2")
      throw HomeError.notFound("No devices support OnOffLightDeviceType")
    }
    
    return automation(
      name: "Turn off light after 5 seconds",
      description:
        """
        Turns off light2 after it has been on for 5 seconds.
        """
    ) {
      let onOffStarter = starter(light, OnOffLightDeviceType.self, OnOffTrait.self)
      onOffStarter
      condition {
        onOffStarter.onOff.equals(true)
      }
      delay(for: Duration.seconds(5))
      action(light, OnOffLightDeviceType.self) {
        OnOffTrait.off()
      }
    }
  }

Işık açıldıktan beş saniye sonra kapanmasını sağlayacak bir otomasyon oluşturmak için otomasyon görünümüne gidin ve "+ Ekle" düğmesini tıklayın. Ardından "Işığı 5 saniye sonra kapat"ı seçin. starter, condition ve action dahil olmak üzere otomasyon ayrıntıları gösterilir. Otomasyonu structure.createAutomation() ile oluşturmak için "Kaydet"i tıklayın.

Not: Kullanılabilen otomasyonlar, evinizdeki cihazlara bağlıdır. Kullanılabilir otomasyon görmüyorsanız ışık cihazınızın adını "ışık2" olarak değiştirmeyi deneyin.

"Cihazlar" sekmesine dönün ve "ışık2" adlı ışığı açın. Beş saniye sonra otomatik olarak kapanır.

Otomasyonun bileşenleri şunlardır:

• Başlatıcı: Bu, otomasyonu başlatan bir etkinliktir. Bu örnekte, otomasyon OnOffTrait üzerinde bir değişiklik olduğunda başlar.
• Koşul: Başlangıç cihazının belirli koşulları karşılayıp karşılamadığını kontrol eder. Bu durumda, ışık açıksa otomasyon yürütülür.
• İşlem: Bu, başlatıcı koşulları karşılıyorsa gerçekleştirmek istediğiniz otomasyondur. Koşullar karşılanırsa ışık kapatılır.

Daha fazla örnek için Örnek otomasyonlar sayfasına göz atın.

Otomasyonu silme

Mevcut bir otomasyonda sola kaydırıp çöp kutusu simgesine dokunarak yapınızdan kaldırdığınızda structure.deleteAutomation() yöntemi çağrılır.

8. Tebrikler

Tebrikler! iOS için Home API'lerini kullanarak temel bir akıllı ev uygulamasını başarıyla oluşturdunuz.

Başarılarınız:

• Başlatma: Home.connect() kullanarak uygulamanızı Google Home ekosistemine bağladınız.
• İzinler: Ev verilerine erişim için kullanıcı kimlik doğrulaması ve yetkilendirmesi işlenir.
• Cihazlar ve Yapılar: home.rooms() ve home.devices() kullanılarak odalar ve cihazlar getirilir ve gösterilir.
• Cihaz kontrolü: Özelliklerindeki komutlar çağrılarak OnOffPluginUnitDeviceType durumunu değiştirme gibi cihaz etkileşimi uygulandı.
• Yapı Yönetimi: Yeni odalar oluşturma (structure.createRoom()), cihazları odalar arasında taşıma (structure.move()) ve boş odaları silme (structure.deleteRoom()) işlevleri eklendi.
• Kullanıma alma: Yeni Matter cihazları (MatterAddDeviceRequest) eklemek için SDK'nın kullanıma alma akışı entegre edildi.
• Otomasyon: Bir yapı içinde otomasyonların nasıl listeleneceği, oluşturulacağı (structure.createAutomation()) ve silineceği (structure.deleteAutomation()) açıklanmıştır.

Artık iOS'te zengin akıllı ev kontrolü deneyimleri oluşturmak için Home API'lerinden nasıl yararlanacağınız konusunda temel bilgilere sahipsiniz.

Sonraki adımlar:

• Örnek uygulamada sağlanan diğer cihaz türlerini (ışıklar, vantilatörler, jaluziler vb.) kontrol etmeyi keşfedin.
• Çeşitli cihazlarda kullanılabilen farklı özellikler ve komutlar hakkında daha ayrıntılı bilgi edinin.
• Farklı başlangıçlar, koşullar ve işlemler kullanarak daha karmaşık otomasyonlar oluşturmayı deneyin.
• Daha gelişmiş özellikler ve ayrıntılar için Home API'leri belgelerine bakın.

Tebrikler!