Ambient API'yi kullanmaya başlama

Ambiyans API, uygulamanızın ambiyans cihazlarını bir kullanıcının Google Fotoğraflar hesabına bağlamasını ve seçtiği fotoğrafları göstermesini sağlar.

Ambient API Akışı

Ambient API'nin bir cihazı bağlamak ve ardından medya öğelerini almak ve görüntülemek için nasıl çalıştığına dair döküm aşağıda verilmiştir:

  1. Mevcut cihaz olup olmadığını kontrol edin (önerilir): Yeni bir cihaz oluşturmadan önce, mevcut kullanıcı için bir cihazın mevcut olup olmadığını kontrol etmeniz önerilir. Uygulamanız, dahili kullanıcınız ile uygulamanız üzerinden oluşturduğu tüm cihazlar için Google tarafından sağlanan deviceId arasında eşleme yapmalıdır. Kullanıcı için bir deviceId bulunursa yetkilendirme jetonunu yenilemeye (gerekirse) devam edebilirsiniz.

  2. OAuth 2.0 yetkilendirmesini başlatın (ve isteğe bağlı olarak cihaz oluşturun): Yetkilendirme kodu isteyerek TV ve Sınırlı Giriş Cihazları için OAuth 2.0 akışını başlatın.

  3. Yeni cihaz oluşturma: Uygulamanız, CreateDevice işlevini çağırarak ve geçerli bir v4 UUID sağlayarak kullanıcının Google Fotoğraflar hesabında bir cihaz oluşturur.

    Cihaz başarıyla oluşturulduktan sonra API, Google tarafından atanan bir deviceId içeren bir AmbientDevice nesnesi döndürür. Uygulamanızın bu deviceId değerini depolamasının ve kullanıcılarınızla ilişkilendirmesinin çok önemli olduğunu unutmayın.

  4. settingsUri'ü gösterin: AmbientDevice nesnesi bir settingsUri içerir. Bu URI'yi kullanıcıya genellikle mobil cihazını kullanarak tarayabileceği bir QR kodu olarak sunun. Bu URI, kullanıcıyı ambiyans cihazında görüntülemek istediği medya kaynaklarını (ör. albümler) yapılandırabileceği Google Fotoğraflar uygulamasına yönlendirir.

  5. mediaSourcesSet için anket: Uygulamanız, ortam cihazının durumunu kontrol etmek için GetDevice yöntemini düzenli olarak çağırarak deviceId değerini sağlamalıdır. AmbientDevice yanıtındaki mediaSourcesSet alanını izleyin. Başlangıçta yanlış olur.

    Kullanıcı Google Fotoğraflar uygulamasında medya kaynaklarını başarıyla seçtikten sonra bu alan true olarak değişir.

    AmbientDevice yanıtı, anket sıklık kılavuzu olarak kullanmanız gereken bir pollInterval içeren bir pollingConfig içerir.

  6. Medya öğelerini getirme: mediaSourcesSet doğru değerini döndürdüğünde uygulamanız, kullanıcı tarafından seçilen medya öğelerini getirmeye başlayabilir.

    deviceId değerini sağlayarak ListMediaItems yöntemini çağırın. API, AmbientMediaItem nesnesinin listesini içeren bir ListMediaItemsResponse döndürür. Her AmbientMediaItem, id, createTime ve ek meta veriler içeren bir MediaFile nesnesi gibi ayrıntılar içerir. MediaFile, bir medya öğesinin gerçek baytlarını almak için kullanabileceğiniz bir baseUrl içerir. Ek baseUrl parametreleri hakkında ayrıntılı bilgi için Medya öğelerini listeleme ve getirme kılavuzunu inceleyin.

  7. Medya öğelerini görüntüleme: Medya içeriğini ambiyans cihazına indirip görüntülemek için MediaFile'daki baseUrl'ü kullanın.

Dikkat Edilecek Önemli Noktalar

Cihaz sınırı ve yönetimi:

  • Cihaz sınırlamaları: Uygulamanızın kullanıcısı başına 100 cihaz sınırı olduğunu unutmayın.
  • Cihaz etkinliği ve jetonlar: Cihazların ve kullanıcı yetkilendirme jetonlarının yaşam döngüsünü yönetmeniz gerekir. Cihazların ne kadar süre boyunca etkin kalacağını ve bir cihaz etkin olmadığında veya jetonun süresi dolduğunda jeton yenileme veya yeniden yetkilendirme işlemlerini nasıl yöneteceğinizi düşünün.

Cihaz oluşturma ve yönetme başlıklı kılavuzda daha fazla bilgi verilmektedir.

Medya öğeleriyle çalışma:

  • Medya öğesi kullanımı: Gerekli kimlik doğrulama veya parametreler dahil olmak üzere baseUrl'ü kullanarak medya öğesi içeriğini nasıl düzgün bir şekilde alıp işleyeceğinizi öğrenin.
  • Hata işleme: Cihazlar için NOT_FOUND, medya kaynakları ayarlanmamışsa FAILED_PRECONDITION ve cihaz sınırlarına ulaşıldığında RESOURCE_EXHAUSTED gibi senaryolar da dahil olmak üzere API çağrıları için güçlü bir hata işleme yöntemi uygulayın.

Medya öğelerini listeleme ve getirme kılavuzunda daha fazla ayrıntı verilmiştir.

Sonraki Adımlar