Ambient API'yi kullanmaya başlama

Ambient API, uygulamanızın ortam cihazlarını kullanıcının Google Fotoğraflar hesabına bağlamasına ve kullanıcının seçtiği fotoğrafları göstermesine olanak tanır.

Ambient API akışı

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

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

2. OAuth 2.0 yetkilendirmesini başlatın: Yetkilendirme kodu isteyerek TV ve sınırlı giriş cihazları için OAuth 2.0 akışını başlatın.

   Not: Ambient API, basitleştirilmiş kimlik doğrulama akışını etkinleştirmek için yetkilendirme isteğinize state parametresini eklemeyi destekler.

3. Yeni cihaz oluşturma: Uygulamanız, CreateDevice yöntemini çağırıp 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 atanmış bir deviceId içeren bir AmbientDevice nesnesi döndürür. Uygulamanızın bu deviceId değerini depolaması ve kullanıcılarınızla ilişkilendirmesi çok önemlidir.

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

5. mediaSourcesSet için yoklama: Uygulamanız, ortam cihazının durumunu kontrol etmek için deviceId sağlayarak GetDevice yöntemini düzenli olarak çağırmalıdır. Yanıttaki AmbientDevice alanında 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ı, yoklama sıklığınız için kılavuz olarak kullanmanız gereken pollInterval içeren bir pollingConfig içerir.

6. Medya öğelerini alma: mediaSourcesSet, "true" değerini döndürdüğünde uygulamanız, kullanıcı tarafından seçilen medya öğelerini almaya başlayabilir.

   ListMediaItems yöntemini çağırarak deviceId değerini sağlayın. API, AmbientMediaItem nesnelerinin 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 alma kılavuzunu inceleyin.

7. Medya Öğelerini Görüntüleme: Medya içeriğini indirip ortam cihazında görüntülemek için MediaFile API'sindeki baseUrl yöntemini kullanın.

Dikkat Edilecek Önemli Noktalar

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

• Cihaz sınırları: Uygulamanızın her kullanıcısı için 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üreyle etkin kalacağını ve bir cihaz etkinliğini kaybederse veya jetonun süresi dolarsa jeton yenileme ya da yeniden yetkilendirme işlemlerini nasıl yapacağınızı göz önünde bulundurun.

Cihaz oluşturma ve yönetme kılavuzunda daha fazla bilgi bulabilirsiniz.

Medya öğeleriyle çalışma:

• Medya öğesi kullanımı: Gerekli kimlik doğrulama veya parametreler de dahil olmak üzere baseUrl kullanarak medya öğesi içeriğini doğru şekilde alma ve işleme hakkında bilgi edinin.
• Hata işleme: API çağrıları için sağlam bir hata işleme yöntemi uygulayın. Bu kapsamda, cihazlar için NOT_FOUND, medya kaynakları ayarlanmamışsa FAILED_PRECONDITION ve cihaz sınırlarına ulaşılmışsa RESOURCE_EXHAUSTED gibi senaryolar yer alır.

Medya öğelerini listeleme ve alma kılavuzunda, içerik politikası ve filtreleme ile ilgili bilgiler de dahil olmak üzere ek ayrıntılar yer almaktadır.

Sonraki Adımlar

• Uygulamanızı yapılandırma: Gerekli kimlik bilgilerine sahip olduğunuzu ve uygulamanızı TV ve Sınırlı Giriş Cihazları için OAuth 2.0'a göre yapılandırdığınızı doğrulayın.
• Ambient API Referans Belgelerini İnceleyin: Kullanılabilir tüm yöntemler, istek ve yanıt parametreleri ve hata kodları için ayrıntılı referans belgelerini inceleyin.