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:
- Uygulamanızı Google API Konsolu'nda kaydedin.
- Yeni bir Google Analytics hesabı oluşturmak için yetki verin.
- 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:
- Kullanıcıdan OAuth 2.0 kullanarak uygulamanın/hizmetin kimliğini doğrulamasını ve yetkilendirmesini isteyin.
- Temel Hazırlık API'sını kullanarak Hesap Bileti oluşturun.
- Kullanıcıyı Google Analytics Hizmet Şartları'nı (TOS) kabul etmesi ve yanıtı işlemesi için yönlendirin.
- (İ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
- İstemci kimliği: Kullanacağınız projenin
Client ID
değeri. Bu özellik Google Developers Console'dan edinilebilir. Daha fazla bilgi edinmek için OAuth 2.0 Web Sunucusu akışı hakkında bilgi edinin. - Yönlendirme URI'si: Kullanıcının yönlendirildiği ve OAuth 2.0 yanıtının gönderildiği yerdir.
Redirect URIs
ürününü yapılandırın ve Google Developers Console'u kullanarak projeniz içinClient ID
edinin.- Bu parametrenin 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.
- Google Analytics Temel Hazırlık API'sı İçin Yetkilendirme Kapsamı
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
veyaedit
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.
- Hesap için
- Web Mülkü alanları
- Mülk için
name
özelliği zorunludur. websiteUrl
gereklidir.
- Mülk için
- Profil alanları
- Profil için
name
özelliği gereklidir. - İsteğe bağlı olarak
timezone
sağlanabilir.America/Los_Angeles
varsayılandır.
- Profil için
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:
- Mümkünse, standart Google Analytics izleme snippet'ini kullanıcının web sitesindeki her sayfa için yeni oluşturulan hesabın Mülk Kimliği ile otomatik olarak ekleyin.
- Management API'sini kullanarak kullanıcının Mülkünü otomatik olarak yapılandırın.
- Embed API veya Core Reporting API'yi kullanarak ürününüzde (ör. yönetici panelinde) kullanıcıya ait raporları sağlayın.
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:
- Google Analytics Hesabı Oluşturma
- 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:
- 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.
- Kullanıcıdan, "Google Analytics Hesapları Oluşturma" için uygulamayı yetkilendirmesi istenir.
- Kullanıcı, uygulamaya ilişkin izin isteğini kabul eder.
- Kullanıcı, Servis Sağlayıcı'ya yönlendirilir. Kullanıcı yetkilendirmeyi reddederse tekrar Servis Sağlayıcı'ya yönlendirileceğini unutmayın.
- 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.
- Kullanıcı, formu doldurup gönderir ve Google'a yönlendirilir/Google Analytics Hizmet Şartları (TOS) gösterilir.
- Kullanıcı, Hizmet Şartları'nı kabul eder.
- 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:
- 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.
- 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.
- Kullanıcıdan, "Google Analytics Hesapları Oluşturma" için uygulamayı yetkilendirmesi istenir.
- Kullanıcı uygulama için istenen izinleri kabul eder.
- Kullanıcı, Servis Sağlayıcı'ya yönlendirilir.
- Kullanıcı Google'a yönlendirilir/Google Analytics Hizmet Şartları görüntülenir.
- Kullanıcı, Hizmet Şartları'nı kabul eder.
- 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.