Kullanıcı Tarafından Kontrol Edilen Hesapların Temel Hazırlığını Yapma – API Geliştirici Kılavuzu

Bu belgede, yeni Google Analytics hesapları oluşturmak için Temel Hazırlık API'sının kullanımıyla ilgili önemli kavramlar açıklanmaktadır.

Giriş

Temel Hazırlık API'sı, yeni Google Analytics hesapları oluşturmak ve müşterileriniz için Google Analytics'i geniş ölçekte etkinleştirmek amacıyla kullanılabilir. Bu özellik, nitelikli servis sağlayıcılar ve büyük iş ortakları için tasarlanmıştır. Temel Hazırlık API'sına giriş için Temel Hazırlık API'sına Genel Bakış sayfasını ziyaret edin.

Başlamadan Önce

Tüm Google Analytics API'lerine benzer şekilde erişilir. Temel Hazırlık API'sını kullanmaya başlamadan önce şunları yapmanız gerekir:

  • API ile çalışan programlama diline özgü istemci kitaplıklarının tam listesi için istemci kitaplıkları sayfasını inceleyin.
  • API arayüzü ve istemci kitaplığı olmadan verilere nasıl erişileceği hakkında bilgi edinmek için Referans Kılavuzu'nu okuyun.

Her istemci kitaplığı, Temel Hazırlık API'sına erişmek için tek bir analiz hizmeti nesnesi sağlar. Hizmet nesnesini oluşturmak için genellikle aşağıdaki adımları uygulamanız gerekir:

  1. Uygulamanızı Google API Konsolu'nda kaydedin.
  2. Yeni bir Google Analytics hesabı oluşturmak için yetki verin.
  3. Bir Analytics hizmet nesnesi oluşturun.

Bu adımları tamamlamadıysanız lütfen durup Merhaba Google Analytics API Eğiticisi'ni okuyun. Bu eğitim, bir Google Analytics API uygulaması oluşturmanın ilk adımlarında size yol gösterecektir. Bu eğitimi tamamladığınızda, gerçek dünyadaki görevleri yerine getirmek için Google Analytics API'lerine nasıl erişeceğinizi anlayacaksınız.

Genel bakış

Temel Hazırlık API'sını kullanarak Google Analytics hesapları oluştururken dikkate alınması gereken 2 ayrı akış vardır:

  • Teknik Akış: Bir kullanıcı için programlı olarak Google Analytics hesabı sağlanmasına yönelik uçtan uca akış.
  • Kullanıcı İşlemleri Akışı: Hesap oluşturma akışı için kullanıcıların bakış açısından dikkate almanız gereken noktalar.

Bu belgede, her bir akışla ilgili üst düzey adımlar ve gereksinimler açıklanmaktadır.

Teknik Akış

Yeni bir hesap oluşturmak ve Google Analytics'le entegrasyon için Konfigürasyon API'sını kullanmak üzere en üst düzey adımlar şunlardır:

  1. Kullanıcıdan OAuth 2.0 kullanarak uygulamanın/hizmetin kimliğini doğrulamasını ve yetkilendirmesini isteyin.
  2. Temel Hazırlık API'sını kullanarak Hesap Bileti oluşturun.
  3. Kullanıcıyı Google Analytics Hizmet Şartları'nı (TOS) kabul etmesi ve yanıtı işlemesi için yönlendirin.
  4. (İsteğe bağlı) Hesabı ve entegrasyon fırsatlarını yapılandırın.

Bu adımların tümü başarıyla tamamlanırsa kullanıcı için bir Google Analytics hesabı oluşturulur ve yeni hesap için Hesap Kimliği, Mülk Kimliği ve Görünüm (Profil) Kimliğine sahip olursunuz.

Aşağıdaki her adım için adımı tamamlamak için Gereksinimler, adımın Sonuçları ve adıma ilişkin Teknik Akış'ın bir açıklaması vardır.

1. Kimlik Doğrulama ve Yetkilendirme

Her kullanıcının uygulamanızı yetkilendirmesi ve uygulamaya kendi adına bir Google Analytics hesabı sağlama yeteneği vermesi gerekir. Bu adımın uygulanması için OAuth 2.0 Web Sunucusu uygulama akışı önerilir.

Bu adımı tamamlamak için gerekenler

Bu adımın sonucu

OAuth 2.0 akışı tamamlandıktan sonra kullanıcı, uygulamanızı kendisi adına hesap sağlama konusunda yetkilendirir ve kullanıcı için bir Erişim Jetonu elde edersiniz.

Jetonlar ve Kapsamlarla İlgili Not:

  • Hesap oluşturulduktan sonra kullanıcının hesap yapılandırması veya raporlama verileri için ek isteklerde bulunmak istiyorsanız bu adımda ek kapsamları da yetkilendirebilirsiniz. Örneğin, readonly veya edit kapsamları.
  • Erişim jetonlarının kullanım ömrü sınırlıdır. Uygulamanızın Google Analytics API'ye tek bir erişim jetonunun kullanım ömrü sonrasında da erişmesi gerekiyorsa access_type=offline özelliğini ayarlayarak yenileme jetonu da isteyebilirsiniz. Yenileme Jetonu, uygulamanızın yeni erişim jetonları elde etmesine olanak tanıdığından her kullanıcı için güvenli bir uzun süreli depolama alanına kaydedilmelidir. Ek ayrıntılar için Çevrimdışı erişim bölümüne bakın.

Bu adımın teknik akışı

Kullanıcı için bir Erişim Jetonu almanız gerekir. OAuth 2.0 Web Sunucusu bölümünde açıklanan akışa göre, kullanıcıyı Google Hesapları hizmetine gönderin ve kimlik doğrulama akışını tamamladıktan sonra kullanıcı hizmetinize geri yönlendirildiğinde verilecek yanıtı ele alın.

Kullanıcının ziyaret edeceği OAuth 2.0 URL'sini oluşturma

Kullanıcı, Başlayın veya Hesap Oluştur'a yönlendiren bir düğmeyi ya da bağlantıyı tıkladığında, kullanıcıdan temel hazırlık izinleri vermesini istemek için bağlantı OAuth 2.0 akışının başlangıcına işaret etmelidir. Örneğin:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
Google Hesapları Hizmetinden Gelen Yanıtı İşleyin

Kullanıcı, uygulamanıza erişim izni verme kararını verdiğinde, oluşturduğunuz URL'de belirtilen redirect_uri adresine, yetkilendirme kodu içeren bir sorgu parametresiyle yönlendirilir. Kullanıcı isteği onayladıysa yetkilendirme kodu yanıtı, Google Accounts API'ye POST isteği göndererek yetkilendirme kodunu bir erişim jetonuyla değiştirmek için kullanılabilir.

Yenileme Jetonunu (varsa) kaydedin

Erişim jetonu, geçici olarak saklamak için bir sonraki adımda kullanılacaktır. Kullanıcı için yenileme jetonu da istediyseniz bunu daha uzun süreli kullanım için güvenli bir şekilde saklamanız gerekir. Yenileme jetonu uzun ömürlüdür ve yeni erişim jetonları yayınlamak için kullanılabilir.

2. Temel Hazırlık API'sını kullanarak Hesap Bileti Oluşturma

Yetkili kullanıcı için erişim jetonunuz olduğunda, Konfigürasyon API'sına kullanıcı için bir Hesap Bileti oluşturmak üzere istekte bulunmak için bu jetonu kullanabilirsiniz. Hesap Bileti, bir kullanıcı için hesap oluşturmanın ilk adımıdır.

Bu adımı tamamlamak için gerekenler

Kimlik Doğrulama ve Yetkilendirme bölümünde açıklanan şekilde, yetkili kullanıcı için bir erişim jetonu ve aşağıdaki temel hazırlık ayrıntıları:

  • Yönlendirme URI'si
    • Kullanıcının Google Analytics Hizmet Şartları sayfasından sonra nereye yönlendirildiğini tanımlar. OAuth 2.0 yetkilendirme akışı sırasında belirtilen yönlendirme URI'sinden farklı olabilir.
    • Yönlendirme URI'si parametresinin değeri, Google Developers Console'da kayıtlı değerlerden (http veya https şemaları, büyük/küçük harf ve sondaki "/" dahil) tam olarak eşleşmelidir.
  • Hesap alanları
    • Hesap için name özelliği gereklidir.
  • Web Mülkü alanları
    • Mülk için name özelliği zorunludur.
    • websiteUrl gereklidir.
  • Profil alanları
    • Profil için name özelliği gereklidir.
    • İsteğe bağlı olarak timezone sağlanabilir. America/Los_Angeles varsayılandır.

Bir hesap kaydı oluştururken yalnızca yukarıda tanımlanan temel alanlar ayarlanabilir. Hesap oluşturulduktan sonra mülkte veya görünümde (profilde) ek yapılandırma değişiklikleri Management API'si kullanılarak yapılabilir.

Bu alanlarla ilgili daha fazla bilgi edinmek için Hesaplar, Mülkler ve Görünümler (Profiller) API Referansı'nı inceleyin.

Bu adımın sonucu

Temel Hazırlık API'sına başarılı bir istek yapıldıktan sonra, kullanıcı için kısa süreli bir Hesap Bileti'ne sahip olursunuz. Hesap Bileti Kimliği, son adımda kullanıcıdan Hizmet Şartları'nı kabul etmesini ve hesabını etkinleştirmesini istemek için kullanılır. Hizmet Şartları kabul edilene kadar hesap kullanılamaz.

Bu adımın teknik akışı

Kimlik Doğrulama ve Yetkilendirme sırasında edinilen kullanıcı için erişim jetonu kullanılarak Konfigürasyon API'sına bir HTTP POST isteği gönderilir.

Hesap Bileti oluşturmak için Temel Hazırlık API'sı İsteği

İsteğin nasıl yapılacağıyla ilgili ayrıntılar için Temel Hazırlık API'sı referansındaki createAccountTicket yöntemini inceleyin.

Temel Hazırlık API'sından yanıt

Başarılı bir istek, 200 yanıtı döndürür. Yanıt gövdesi, kısa ömürlü bir Hesap Bileti içerir. Hesap bileti, yeni hesap ağacıyla ilgili kimlik ve ayrıntılardan oluşur.

Yanıtla ilgili ayrıntılar için Temel Hazırlık API'sı referansındaki Account Ticket resource bölümüne göz atın.

Hata yanıtlarının da uygulama tarafından işlenmesi gerekir.

3. Kullanıcı Google Analytics Hizmet Şartları'nı (TOS) Kabul Eder

Kullanıcı için bir Hesap Bileti Kimliği elde ettikten sonra, kullanıcıdan Google Analytics Hizmet Şartları'nı kabul etmesini istemek için bu kimliği Hizmet Şartları isteğiyle birlikte kullanabilirsiniz.

Bu adımı tamamlamak için gerekenler

Yetkili kullanıcının Hesap Bileti Kimliği.

Bu adımın sonucu

Hesap Bileti Kimliği kullanılarak Hizmet Şartları Akışı başarıyla tamamlandıktan sonra hesap, mülk ve görünüm (profil) oluşturulur. Kullanıcı artık etkin bir hesaba sahip olur. Hizmet Şartları sayfasından gelen yanıtta Hesap Kimliği, Mülk Kimliği ve Görünüm (Profil) Kimliği bulunur.

Bu adımın teknik akışı

Hesap Bileti Kimliğini kullanarak kullanıcıyı, Hizmet Şartları'nı kabul edebilecekleri Google Analytics Hizmet Şartları sayfasına yönlendirin. Sonrasında API'den gelen yanıtı ele almanız gerekir.

Kullanıcının ziyaret edebileceği Hizmet Şartları URL'sini oluşturun

Kullanıcıyı Hizmet Şartları sayfasına yönlendirin ve Hesap Bileti Kimliğini URL'ye ekleyin:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Hizmet Şartları yanıtını işleme

Kullanıcı, Hizmet Şartları sayfasında işlem yaptıktan sonra hesap bileti oluşturma sırasında belirtilen redirectUri hizmetine tekrar yönlendirilir. Hizmet Şartları sayfasından gelen yanıt, sorgu dizesinin bir parçası olarak eklenir.

Başarılı yanıtlar, yeni oluşturulan hesap yapısı ve orijinal accountTicketId hakkında veriler döndürür:

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

Örneğin, uygulamanızın Hizmet Şartları işleyici http://www.your-app.com/gaTOS konumundaysa hesap biletleri oluştururken bu değer redirectUri olarak ayarlanmalıdır. Uygulamanızın Hizmet Şartları işleyicisi, hesap biletinin geçerli olduğu ve kullanıcının Hizmet Şartları'nı kabul ettiği durumlarda accountId, webPropertyId, profileId ve accountTicketId sorgu parametrelerini içeren HTTP GET isteklerini beklemeli ve doğru şekilde işlemelidir.

Başarısız yanıtlar hata yanıtını içerir:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

Hizmet Şartları işleyicinizin de error sorgu parametresi içeren HTTP GET isteklerini düzgün şekilde işlemesi gerekir. Bu durum, bir şeylerin ters gittiğini gösterir. Sorgu parametresinin değeri, başka işlem yapmak veya kullanıcıya bir mesaj göstermek için kullanılabilir:

  • error=user_cancel - Kullanıcı, hizmet şartlarını kabul etmedi.
  • error=max_accounts_reached - Kullanıcı, Google Analytics hesap sınırına ulaştı.
  • error=backend_error - Genel bir hata. Sunucu yukarıdaki kategorilerde olmayan bir hata döndürdü.

4. (İsteğe bağlı) Entegrasyon Fırsatları

Yukarıdaki Teknik Akış'ı izlediyseniz kullanıcı için bir hesap oluşturmuş ve Hesap Kimliği, Mülk Kimliği ve Görünüm (Profil) Kimliğine sahip olursunuz. Ek izinler de istediyseniz kullanıcı için yenileme jetonunuz da olabilir. Bu verilerle şunları yapabilirsiniz:

Kullanıcı İşlemleri Akışı

Bu bölümde, kullanıcı açısından hesap oluşturma akışının adımlarıyla ilgili uygulama sırasında dikkat edilmesi gereken hususlar açıklanmaktadır.

Akış, kullanıcının mülkünde analizi etkinleştirmek için aşağıdaki 2 seçeneği sunmasıyla başlar:

  1. Google Analytics Hesabı Oluşturma
  2. Mevcut bir Google Analytics hesabını kullanın. (Not: Bu akış bu dokümanda ele alınmamıştır. Kullanıcının Google Analytics yapılandırma verilerine nasıl erişileceğiyle ilgili ayrıntılar için Management API'yi inceleyin.)

Yeni bir Google Analytics hesabı oluştururken hesap adı, mülk adı vb. gibi temel hazırlık isteğiyle birlikte göndermeniz gereken bilgiler bulunur. Kullanıcı hakkında sahip olduğunuz bilgilere ve kullanıcıya göstermek istediğiniz tercih edilen akışa bağlı olarak, kullanıcı "hesap oluştur"u tıkladıktan sonra kullanıcı akışını başlatmak için 3 ana seçenek vardır:

Yetkilendirmeden sonra hesap ayrıntılarını isteyin

Bu durumda, işlemin ortasında kullanıcıdan hesap ayrıntıları istenir. Akış aşağıdakine benzer olacaktır:

  1. Kullanıcı, OAuth 2.0 akışı için Google Hesap Hizmeti'ne yönlendirilir. Kullanıcının Google Hesabı yoksa veya oturum açmamışsa Google Hesabı oluşturması veya oturum açması istenir.
  2. Kullanıcıdan, "Google Analytics Hesapları Oluşturma" için uygulamayı yetkilendirmesi istenir.
  3. Kullanıcı, uygulamaya ilişkin izin isteğini kabul eder.
  4. Kullanıcı, Servis Sağlayıcı'ya yönlendirilir. Kullanıcı yetkilendirmeyi reddederse tekrar Servis Sağlayıcı'ya yönlendirileceğini unutmayın.
  5. Oluşturulacak hesapla ilgili ayrıntıları (ör.Hesap adı, mülk adı, profil adı, saat dilimi, web sitesi URL'si vb.) toplaması için kullanıcıya bir form sunulur.
  6. Kullanıcı, formu doldurup gönderir ve Google'a yönlendirilir/Google Analytics Hizmet Şartları (TOS) gösterilir.
  7. Kullanıcı, Hizmet Şartları'nı kabul eder.
  8. Servis Sağlayıcı'ya yönlendirilir ve kullanıcıya, hesapla ve hesaba nasıl erişileceğine ilişkin ayrıntıların yer aldığı bir Google Analytics hesabını başarıyla oluşturduğunu belirten bir başarı mesajı gösterilir. Kullanıcı, Hizmet Şartları'nı kabul etmezse tekrar Servis Sağlayıcı'ya yönlendirilir.

Yetkilendirmeden önce hesap bilgilerini isteyin

Bu durumda, önceden kullanıcıdan oluşturulacak hesabın yapılandırma ayrıntıları istenir. Akış aşağıdakine benzer olacaktır:

  1. Servis sağlayıcı sitesinde, oluşturulacak hesapla ilgili ayrıntıları (ör. Hesap adı, mülk adı, profil adı, saat dilimi, web sitesi URL'si) toplamak için kullanıcıya bir form sunulur.
  2. Kullanıcı, formu doldurur, gönder düğmesini tıklar ve OAuth 2.0 akışı için Google Hesabı Hizmeti'ne yönlendirilir. Kullanıcının Google Hesabı yoksa veya oturum açmamışsa Google Hesabı oluşturması veya oturum açması istenir.
  3. Kullanıcıdan, "Google Analytics Hesapları Oluşturma" için uygulamayı yetkilendirmesi istenir.
  4. Kullanıcı uygulama için istenen izinleri kabul eder.
  5. Kullanıcı, Servis Sağlayıcı'ya yönlendirilir.
  6. Kullanıcı Google'a yönlendirilir/Google Analytics Hizmet Şartları görüntülenir.
  7. Kullanıcı, Hizmet Şartları'nı kabul eder.
  8. Servis Sağlayıcı'ya yönlendirilir ve kullanıcıya, hesapla ve hesaba nasıl erişileceğine ilişkin ayrıntıların yer aldığı bir Google Analytics hesabını başarıyla oluşturduğunu belirten bir başarı mesajı gösterilir.

Hesap ayrıntılarını önceden doldurun veya formları atlayın

Kullanıcı hesabıyla ilgili bilgiler zaten mevcutsa (ör. web sitesi URL'si, web sitesi adı, saat dilimi vb.) yukarıdaki her iki seçenek de aşağıdaki şekilde daha da basitleştirilebilir:

  • Formu önceden doldurma ve isterse kullanıcının düzenleme yapmasına izin verme
  • Form adımını tamamen atlamak ve mevcut bilgileri kullanarak hesabı otomatik olarak oluşturmak.