Uygulamanızı Ambient API için yapılandırın

Ambient API'yi kullanmaya başlamak için Google API Konsolu'nda API'yi etkinleştirip bir OAuth 2.0 istemci kimliği oluşturarak projenizi yapılandırın. Ambient API, TV ve Sınırlı Giriş Aygıtı Uygulamaları için OAuth 2.0'ı kullanır.

Uygulamanız, Ambient API kullanıcısı adına Ambient API ile etkileşimde bulunuyor. Kullanıcı, bu API isteklerini OAuth 2.0 protokolünü kullanarak yetkilendirir.

OAuth 2.0 istemci kimliği, uygulama kullanıcılarınızın oturum açmasına, kimlik doğrulamasına ve böylece Ambient API'yi kullanmasına olanak tanır. Ambient API, hizmet hesaplarını desteklemez. Bu API'leri kullanmak için kullanıcıların geçerli bir Google Hesabı'nda oturum açmış olması gerekir.

Uygulamanızı yapılandırma

Önce API'yi etkinleştirin, ardından OAuth 2.0 istemci kimliği isteyin.

API'yi etkinleştirme

Ambient API'yi kullanabilmek için projenizde etkinleştirmeniz gerekir.

1. Google API Konsolu'na gidin.
2. Menü çubuğundan bir proje seçin veya yeni bir proje oluşturun.
3. Google Fotoğraflar API'lerinden birini açmak için Gezinme menüsünden API'ler ve Hizmetler > Kitaplık'ı seçin.
4. "Ambient API" araması yapın. Ambient API'yi seçin ve Etkinleştir'i tıklayın.

OAuth 2.0 istemci kimliği isteme

OAuth istemci kimliği istemek ve uygulamanız için yapılandırmak üzere aşağıdaki adımları uygulayın. Ambient API, TV ve Sınırlı Giriş Aygıtı Uygulamaları için OAuth 2.0'ı kullanır.

1. Google API Konsolu'na gidip projenizi seçin.
2. Menüden API'ler ve Hizmetler > Kimlik Bilgileri'ni seçin.

3. Kimlik bilgileri sayfasında Kimlik bilgileri oluştur > OAuth istemci kimliği'ni tıklayın.

   Not: Yeni bir proje oluşturuyorsanız projenizin izin ekranını yapılandırmanız istenebilir.

4. Uygulama türünüzü seçin. Bu örnekte uygulama türü TV'ler ve Sınırlı Giriş cihazları'dır.

5. OAuth 2.0 istemciniz için bir ad girip Oluştur'u tıklayın.

6. Açılan OAuth istemcisi iletişim kutusunda şunları kopyalayın:

   • Müşteri Kimliği
   • İstemci gizli anahtarı

Uygulamanız, etkinleştirilen Google API'lerine bu değerleri kullanarak erişebilir.

Ambient API'ye erişen herkese açık bir uygulama yayınlayabilmeniz için uygulamanızın Google tarafından incelenmesi gerekir. Uygulamanızı test ettiğinizde, doğrulanana kadar ekranda "Doğrulanmamış uygulama" mesajı gösterilir.

Uygulamanızı yapılandırdıktan sonra çalışmaya başlayabilirsiniz. Aşağıdaki kaynakları inceleyebilir veya Ambient API için basitleştirilmiş kimlik doğrulama akışı hakkında daha fazla bilgi edinebilirsiniz.

• Cihaz oluşturma ve yönetme
• Medya öğelerini listeleme ve alma

İstemci kimliğinizi değiştirme

Google Fotoğraflar API'lerinden herhangi biri aracılığıyla oluşturulan kaynaklara yalnızca oluşturulurken kullanılan orijinal istemci kimliği kullanılarak erişilebilir veya bu kaynaklarda değişiklik yapılabilir. Örneğin, Picker API'de belirli bir istemci kimliğiyle bir session oluşturur ve daha sonra uygulamanızda bu istemci kimliğini değiştirirseniz uygulamanız önceki istemci kimliğiyle oluşturulan API kaynaklarına erişimi kaybeder.

Kullandığınız Fotoğraflar API'si için dikkatli bir şekilde planlama yapın ve doğru istemci kimliği türünü seçin. Erişim sorunlarını önlemek için yalnızca kesinlikle gerekli olduğunda istemci kimliğinizi değiştirin.

Ambient API için basitleştirilmiş kimlik doğrulama akışı

Standart Ambient API kimlik doğrulama akışında, kullanıcılarınızın 2 QR kodunu taraması gerekir:

• Google Hesabında oturum açması (henüz oturum açmadıysa).
• İkincisi, Google Fotoğraflar hesaplarında yeni oluşturulan Ambiyans cihazına bağlantı veren ve görüntülenecek medya öğelerini seçebilecekleri bir cihaz.

Basitleştirilmiş akış, ilk kimlik doğrulama çağrınızla ek state parametresini ileterek kullanıcılarınıza tek bir QR kodu sağlamanıza olanak tanır.

Sınırlı giriş cihazları için OAuth'un bir parçası olarak cihaz ve kullanıcı kodları istediğinizde isteğinize ek state parametresini ekleyin. state parametresine aşağıdakileri ekleyin:

Parametreler
requestId	string Zorunlu. Bu istek için istemci tarafından sağlanan benzersiz tanımlayıcı. Bu, ağ hatası durumunda kaynak yinelemesini azaltmak için kullanılır. Bu kimlik, UUID (4. sürüm) dizesi biçiminde olmalı ve aşağıdaki koşulları karşılamalıdır: Kullanıcıyla ilgili hassas tanımlayıcı bilgiler içermemelidir. "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (veya 8-4-4-4-12) biçiminde, kısa çizgilerle ayrılmış beş gruba bölünmüş 32 on altılı karakter içermelidir.
displayName	string İsteğe bağlı. Bu cihaz için kullanıcı tanımlı görünen ad. Bu bilgi, Google Fotoğraflar uygulaması ayarlarından kullanıcılara gösterilir ancak yalnızca bu API üzerinden düzenlenebilir. Geçerli görünen adlar 1 ila 100 karakter (dahil) arasında olmalıdır.

Örneğin, aşağıdaki kod bloğuna bakın:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

Başarılı bir yanıtta bir user_code ve bir verification_url bulunur. Bu öğeleri, kullanıcının ayrı bir cihazda bu sayfaya gidebilmesi için ona (muhtemelen QR kodu olarak) gösterirsiniz. state parametresini ekleyerek, daha sonra Ambient API ile createDevice'u çağırdığınızda settingsUri'yi ikinci bir QR kodunda sunmayı atlayabilirsiniz. OAuth akışındaki son adım otomatik olarak bu konuma yönlendireceğinden, settingsUri'yi ikinci bir QR kodunda sunmayı atlayabilirsiniz.

Ayrıntılı bilgi için daha ayrıntılı bir açıklama ekledik. Ambient API'yi kullanan sınırlı giriş cihazları için OAuth'un bir parçası olarak state parametresinin kullanılmasına dair örnek için örnek uygulamamızdaki kodu da inceleyebilirsiniz.

Basitleştirilmiş kimlik doğrulama akışı hakkında ayrıntılar

Ambient API için basitleştirilmiş OAuth akışını tam olarak anlamak amacıyla hem TV ve Sınırlı Giriş Aygıtı Uygulamaları için OAuth 2.0 akışını hem de standart Ambient API akışını anlamanız gerekir. Her akış için uygulanacak adımlar aşağıda verilmiştir.

TV ve Sınırlı Giriş Cihaz Uygulamaları için OAuth 2.0:

1. Uygulamanız, Google'ın yetkilendirme sunucusuna bir istek gönderir. Bu istek, uygulamanızın erişim izni isteyeceği kapsamları tanımlar.
2. Sunucu, sonraki adımlarda kullanılan çeşitli bilgilerle (ör. cihaz kodu ve kullanıcı kodu) yanıt verir.
3. Kullanıcının uygulamanızı yetkilendirmek için ayrı bir cihazda girebileceği bilgileri gösterirsiniz.
4. Uygulamanız, kullanıcının uygulamanıza yetki verip vermediğini belirlemek için Google'ın yetkilendirme sunucusunu yoklamaya başlar.
5. Kullanıcı, daha zengin giriş özelliklerine sahip bir cihaza geçer, bir web tarayıcısı başlatır, 3. adımda gösterilen URL'ye gider ve 3. adımda da gösterilen bir kodu girer. Kullanıcı daha sonra uygulamanıza erişim izni verebilir (veya reddedebilir).
6. Anket isteğinize verilen bir sonraki yanıt, uygulamanızın kullanıcı adına istekleri yetkilendirmek için ihtiyaç duyduğu jetonları içerir. (Kullanıcı uygulamanıza erişimi reddettiyse yanıt jeton içermez.)

Ambient API akışı:

1. Mevcut bir OAuth jetonu olup olmadığını kontrol edin ve jetonu yenileyin veya yeni bir jeton isteyin.
2. OAuth jetonu aldıktan sonra yeni bir cihaz oluşturun.
3. settingsUri değerini kullanıcıya gösterin ve mediaSourcesSet doğru değerini döndürene kadar cihazı yoklamaya başlayın.
4. Kullanıcı, settingsUri bölümüne gidip uygulamanızla paylaşmak istediği fotoğrafları seçer.
5. mediaSourcesSet doğru değerini döndürdüğünde mediaItems listesini alın.
6. Artık slayt gösterinize veya diğer ambiyans deneyiminize başlayabilirsiniz.

Her iki akış da kullanıcınıza bir URL gösterdiğiniz ve kullanıcınızın daha zengin giriş cihazında bu URL'ye gittiği bir adım içerir. İlk OAuth çağrınıza state parametresini ekleyerek göstermeniz gereken ikinci URL'den kaçınabilirsiniz.

Bu, TV ve Sınırlı Girişli Cihaz Uygulamaları için OAuth 2.0 akışının son adımı normalde kullanıcınızı "Artık cihazınıza dönebilirsiniz" yazan bir sayfaya yönlendirdiği için işe yarar. Durum parametresini ekleyerek akıştaki son adım artık sizi settingsUri adresine yönlendirmeye çalışacaktır. Uygulamanız yine de bir OAuth jetonu alır. Aynı requestId'ı kullanarak createDevice'i çağırmak için bu jetonu kullanmanız gerekir. Aynı kimliğe sahip bir cihaz oluşturulduktan sonra ilk OAuth akışı, kullanıcınızı Fotoğraflar uygulamasındaki zengin cihazda doğru sayfaya başarıyla yönlendirir.

Aşağıdaki noktaları unutmayın:

• Kimlik doğrulamayla ilgili herhangi bir sorun olması ihtimaline karşı settingsUri simgesini göstermeniz önerilir.
• Kullanıcıların fotoğraf seçimlerini güncellemek istemesi gibi diğer durumlarda settingsUri simgesini kullanmaya devam edebilirsiniz.