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 seçilen 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 cihazları kontrol edin (önerilir): Yeni bir cihaz oluşturmadan önce, mevcut kullanıcı için bir cihazın zaten 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 yetkilendirme jetonunu yenilemeye (gerekirse) devam edebilirsiniz.

  2. OAuth 2.0 yetkilendirmesini başlatma (ve isteğe bağlı olarak cihaz oluşturma): 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ğı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 saklaması ve kullanıcılarınızla ilişkilendirmesi çok önemlidir.

  4. settingsUri öğesini gösterin: AmbientDevice nesnesi 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. AmbientDevice yanıtındaki mediaSourcesSet alanını izleyin. Başlangıçta false (yanlış) olacaktır.

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

    AmbientDevice yanıtı, yoklama sıklığınız için kılavuz olarak kullanmanız gereken bir pollInterval içeren pollingConfig içerir.

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

    ListMediaItems yöntemini çağırın ve 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ı getirmek 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 ortam cihazına indirmek ve görüntülemek için MediaFile bölümündeki baseUrl simgesini kullanın.

Dikkat Edilecek Önemli Noktalar

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

  • Cihaz sınırları: Uygulamanızın kullanıcı başına 100 cihaz sınırına dikkat edin.
  • 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 devre dışı kalırsa 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 ek bilgiler yer almaktadır.

Medya öğeleriyle çalışma:

  • Medya öğesi kullanımı: Gerekli kimlik doğrulama veya parametreler de dahil olmak üzere baseUrl kullanarak medya öğesi içeriğinin nasıl doğru şekilde getirileceğini ve işleneceğini öğrenin.
  • Hata işleme: Cihazlar için NOT_FOUND, medya kaynakları ayarlanmamışsa FAILED_PRECONDITION ve cihaz sınırlarına ulaşılmışsa RESOURCE_EXHAUSTED gibi senaryolar da dahil olmak üzere API çağrıları için güçlü hata işleme uygulayın.

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