Bu geliştirici kılavuzunda, Google Etiket Yöneticisi'nin bir mobil uygulamada nasıl uygulanacağı açıklanmaktadır.
Giriş
Google Etiket Yöneticisi, geliştiricilerin mobil uygulamalarındaki yapılandırma değerlerini Google Etiket Yöneticisi arayüzünü kullanarak değiştirmesine olanak tanır. Bu sayede, uygulama ikili programlarını yeniden derleyip uygulama mağazalarına tekrar göndermeleri gerekmez.
Bu, uygulamanızda gelecekte değiştirmeniz gerekebilecek yapılandırma değerlerini veya işaretleri yönetmek için kullanışlıdır. Örneğin:
- Çeşitli kullanıcı arayüzü ayarları ve görüntüleme dizeleri
- Uygulamanızda yayınlanan reklamların boyutları, konumları veya türleri
- Oyun ayarları
Yapılandırma değerleri, çalışma zamanında kurallar kullanılarak da değerlendirilebilir. Bu sayede aşağıdaki gibi dinamik yapılandırmalar yapılabilir:
- Reklam banner'ı boyutunu belirlemek için ekran boyutunu kullanma
- Kullanıcı arayüzü öğelerini yapılandırmak için dil ve konum kullanma
Google Etiket Yöneticisi, uygulamalarda izleme etiketlerinin ve piksellerinin dinamik olarak uygulanmasını da sağlar. Geliştiriciler, önemli etkinlikleri bir veri katmanına aktarabilir ve daha sonra hangi izleme etiketlerinin veya piksellerinin tetikleneceğine karar verebilir. TagManager aşağıdaki etiketleri destekler:
- Google Mobil Uygulama Analizi
- Özel İşlev Çağrısı etiketi
Başlamadan Önce
Bu başlangıç kılavuzunu kullanmadan önce aşağıdakilere ihtiyacınız vardır:
- Google Etiket Yöneticisi hesabı
- Yeni bir Etiket Yöneticisi kapsayıcısı ve değer toplama makrosu
- Google Etiket Yöneticisi'nin uygulanacağı Android için mobil uygulama
- Etiket Yöneticisi kitaplığını içeren Google Analytics Hizmetleri SDK'sı.
Google Etiket Yöneticisi'ni kullanmaya yeni başladıysanız bu kılavuzu okumaya devam etmeden önce kapsayıcılar, makrolar ve kurallar hakkında daha fazla bilgi edinmenizi (Yardım Merkezi) öneririz.
Başlarken
Bu bölümde, geliştiricilere tipik bir Etiket Yöneticisi iş akışı açıklanmaktadır:
- Google Etiket Yöneticisi SDK'sını projenize ekleme
- Varsayılan kapsayıcı değerlerini ayarlama
- Kapsayıcıyı açma
- Kapsayıcıdan yapılandırma değerlerini alma
- Etkinlikleri DataLayer'a aktarma
- Kapsayıcıyı önizleme ve yayınlama
1. Google Etiket Yöneticisi SDK'sını projenize ekleme
Google Etiket Yöneticisi SDK'sını kullanmadan önce SDK paketini çıkarmanız, kitaplığı projenizin derleme yoluna eklemeniz ve AndroidManifest.xml dosyanıza izinler eklemeniz gerekir.
Öncelikle Google Etiket Yöneticisi kitaplığını projenizin /libs klasörüne ekleyin.
Ardından, AndroidManifest.xml dosyanızı aşağıdaki izinleri kullanacak şekilde güncelleyin:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" />
2. Projenize varsayılan kapsayıcı dosyası ekleme
Google Etiket Yöneticisi, uygulamanızın ilk çalıştırılışında varsayılan bir kapsayıcı kullanır. Uygulama, ağ üzerinden yeni bir kapsayıcı alana kadar varsayılan kapsayıcı kullanılır.
Varsayılan bir kapsayıcı ikili programını indirip uygulamanıza eklemek için aşağıdaki adımları uygulayın:
- Google Etiket Yöneticisi web arayüzünde oturum açın.
- İndirmek istediğiniz kapsayıcının Sürüm'ünü seçin.
- Kapsayıcı ikili programını almak için İndir düğmesini tıklayın.
- İkili program dosyasını şu yola ekleyin:
<project-root>/assets/tagmanager/
Varsayılan dosya adı, kapsayıcı kimliği (ör. GTM-1234) olmalıdır. İkili program dosyasını indirdikten sonra, doğru adlandırma kuralına uymak için dosya adından sürüm son ekini kaldırdığınızdan emin olun.
İkili program dosyasının kullanılması önerilse de kapsayıcınız kural veya etiket içermiyorsa bunun yerine JSON dosyası kullanmayı tercih edebilirsiniz. Dosya, Android projenizin yeni bir /assets/tagmanager klasöründe bulunmalı ve şu adlandırma kuralına uymalıdır: <Container_ID>.json. Örneğin, kapsayıcı kimliğiniz GTM-1234 ise varsayılan kapsayıcı değerlerinizi /assets/tagmanager/GTM-1234.json dosyasına eklemeniz gerekir.
3. Kapsayıcı açma
Uygulamanızın bir kapsayıcıdan değerleri alabilmesi için kapsayıcıyı açması gerekir. Bir kapsayıcı açıldığında diskten yüklenir (varsa) veya ağdan istenir (gerekirse).
Android'de kapsayıcı açmanın en kolay yolu, aşağıdaki örnekte gösterildiği gibi ContainerOpener.openContainer(..., Notifier notifier) kullanmaktır:
import com.google.tagmanager.Container; import com.google.tagmanager.ContainerOpener; import com.google.tagmanager.ContainerOpener.OpenType; import com.google.tagmanager.TagManager; import android.app.Activity; import android.os.Bundle; public class RacingGame { // Add your public container ID. private static final String CONTAINER_ID = "GTM-YYYY"; volatile private Container mContainer; @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); TagManager mTagManager = TagManager.getInstance(this); // The container is returned to containerFuture when available. ContainerOpener.openContainer( mTagManager, // TagManager instance. CONTAINER_ID, // Tag Manager Container ID. OpenType.PREFER_NON_DEFAULT, // Prefer not to get the default container, but stale is OK. null, // Time to wait for saved container to load (ms). Default is 2000ms. new ContainerOpener.Notifier() { // Called when container loads. @Override public void containerAvailable(Container container) { // Handle assignment in callback to avoid blocking main thread. mContainer = container; } } ); // Rest of your onCreate code. } }
Bu örnekte, yerel depolama alanından kayıtlı bir kapsayıcı istemek için ContainerOpener.openContainer(..., Notifier notifier) kullanılıyor. mContainer atamasını containerAvailable geri çağırma işlevinde gerçekleştirerek ana iş parçacığının engellenmemesini sağlarız. Kayıtlı kapsayıcı 12 saatten eskiyse çağrı, ağ üzerinden eşzamansız olarak yeni bir kapsayıcı almak için bir istek de planlar.
Bu örnek uygulama, ContainerOpener kolaylık sınıfını kullanarak bir container'ı açmanın ve container'dan değerleri almanın en basit yolunu gösterir.
Daha gelişmiş uygulama seçenekleri için Gelişmiş Yapılandırma bölümüne bakın.
4. Kapsayıcıdan Yapılandırma Değerlerini Alma
Kapsayıcı açıldıktan sonra yapılandırma değerleri get<type>Value() yöntemleri kullanılarak alınabilir:
// Retrieving a configuration value from a Tag Manager Container. // Get the configuration value by key. String title = mContainer.getStringValue("title_string");
Mevcut olmayan bir anahtarla yapılan istekler, istenen türe uygun varsayılan bir değer döndürür:
// Empty keys will return a default value depending on the type requested. // Key does not exist. An empty string is returned. string subtitle = container.getStringValue("Non-existent-key"); subtitle.equals(""); // Evaluates to true.
5. Değerleri dataLayer'a aktarma
DataLayer, uygulamanızla ilgili çalışma zamanı bilgilerinin (ör. dokunma etkinlikleri veya ekran görüntülemeleri) bir kapsayıcıdaki Etiket Yöneticisi makroları ve etiketleri tarafından kullanılabilir hale gelmesini sağlayan bir eşlemedir.
Örneğin, ekran görüntülemeleriyle ilgili bilgileri DataLayer haritasına aktararak, Etiket Yöneticisi web arayüzünde etiketleri, bu ekran görüntülemelerine yanıt olarak dönüşüm piksellerini ve izleme çağrılarını uygulamanıza sabit kodlamaya gerek kalmadan tetikleyecek şekilde ayarlayabilirsiniz.
Etkinlikler, push() ve DataLayer.mapOf() yardımcı yöntemi kullanılarak DataLayer'a aktarılır:
// // MainActivity.java // Pushing an openScreen event with a screen name into the data layer. // import com.google.tagmanager.TagManager; import com.google.tagmanager.DataLayer; import android.app.Activity; import android.os.Bundle; public MainActivity extends Activity { public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); } // This screen becomes visible when Activity.onStart() is called. public void onStart() { super.onStart(); // The container should have already been opened, otherwise events pushed to // the DataLayer will not fire tags in that container. DataLayer dataLayer = TagManager.getInstance(this).getDataLayer(); dataLayer.push(DataLayer.mapOf("event", "openScreen", // The event type. This value should be used consistently for similar event types. "screenName", // Writes a key "screenName" to the dataLayer map. "Home Screen") // Writes a value "Home Screen" for the "screenName" key. ); } // Rest of the Activity implementation }
Web arayüzünde, şu kuralı oluşturarak her ekran görüntülemesi için tetiklenecek etiketler (Google Analytics etiketleri gibi) oluşturabilirsiniz: eşittir "openScreen". Ekran adını bu etiketlerden birine iletmek için veri katmanındaki "screenName" anahtarına başvuran bir veri katmanı makrosu oluşturun. Ayrıca, "openScreen" ve "ConfirmationScreen" değerine eşit olacak şekilde bir kural oluşturarak yalnızca belirli ekran görüntülemeleri için etkinleşecek bir etiket (ör. Google Ads reklam dönüşümü pikseli) oluşturabilirsiniz.
6. Kapsayıcı Önizleme ve Yayınlama
Makro değerleri her zaman mevcut yayınlanan sürüme karşılık gelir. Bir kapsayıcının en yeni sürümünü yayınlamadan önce taslak kapsayıcınızı önizleyebilirsiniz.
Bir kapsayıcıyı önizlemek için Google Etiket Yöneticisi web arayüzünde önizlemek istediğiniz kapsayıcı sürümünü seçip Preview simgesini tıklayarak bir önizleme URL'si oluşturun. Bu önizleme URL'sini kaydedin. Sonraki adımlarda bu URL'ye ihtiyacınız olacak.
Ardından, uygulamanızın AndroidManifest.xml dosyasına aşağıdaki etkinliği ekleyin:
<!-- Google Tag Manager Preview Activity --> <activity android:name="com.google.tagmanager.PreviewActivity" android:label="@string/app_name" android:noHistory="true" > <!-- Optional, removes the PreviewActivity from activity stack. --> <intent-filter> <data android:scheme="tagmanager.c.application_package_name" /> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE"/> </intent-filter> </activity>
Uygulamanızdaki taslak kapsayıcıyı önizlemek için bağlantıyı bir emülatörde veya fiziksel cihazda açın.
Taslak yapılandırma değerlerinizi uygulamanızda kullanmaya hazır olduğunuzda kapsayıcıyı yayınlayın.
Gelişmiş Yapılandırma
Mobil için Google Etiket Yöneticisi'nde, kuralları kullanarak çalışma zamanı koşullarına göre değer seçmenize, kapsayıcıyı manuel olarak yenilemenize ve kapsayıcıları açmak için ek seçenekler elde etmenize olanak tanıyan bir dizi gelişmiş yapılandırma seçeneği bulunur. Aşağıdaki bölümlerde, en yaygın gelişmiş yapılandırmalardan bazıları açıklanmaktadır.
Kapsayıcıları Açmak İçin Gelişmiş Seçenekler
Google Etiket Yöneticisi SDK'sı, yükleme işlemi üzerinde daha fazla kontrol sahibi olmanızı sağlayacak kapsayıcıları açmak için çeşitli yöntemler sunar:
TagManager.openContainer()
TagManager.openContainer(), kapsayıcı açmak için en düşük düzeyde ve en esnek API'dir. Varsayılan bir kapsayıcıyla hemen döndürülür ve kaydedilmiş bir kapsayıcı yoksa veya kaydedilmiş kapsayıcı güncel değilse (> 12 saatlik) diskten ya da ağdan eşzamansız olarak bir kapsayıcı yükler.
mContainer = tagManager.openContainer(CONTAINER_ID, new Container.Callback() { // Called when a refresh is about to begin for the given refresh type. @Override public void containerRefreshBegin(Container container, RefreshType refreshType) { // Notify UI that the Container refresh is beginning. } // Called when a successful refresh occurred for the given refresh type. @Override public void containerRefreshSuccess(Container container, RefreshType refreshType]) { // Notify UI that Container is ready. } // Called when a refresh failed for the given refresh type. @Override public void containerRefreshFailure(Container container, RefreshType refreshType, RefreshFailure refreshFailure) { // Notify UI that the Container refresh has failed. }
Yükleme işlemi boyunca TagManager.openContainer(), kodunuzun yükleme isteğinin ne zaman başladığını, başarısız olup olmadığını ve nedenini ya da başarılı olup olmadığını ve kapsayıcının sonuçta diskten mi yoksa ağdan mı yüklendiğini öğrenebilmesi için birkaç yaşam döngüsü geri çağırma yöntemi yayınlar.
Uygulamanızın varsayılan değerleri kullanması kabul edilebilir değilse kaydedilmiş veya ağ kapsayıcısının ne zaman yüklendiğini öğrenmek için bu geri çağırmaları kullanmanız gerekir. Uygulama ilk kez çalıştırılıyorsa ve ağ bağlantısı yoksa kaydedilmiş veya ağ kapsayıcısı yükleyemezsiniz.
TagManager.openContainer(), bu geri çağırmalara bağımsız değişken olarak aşağıdaki enum değerlerini iletir:
RefreshType
| Değer | Açıklama |
|---|---|
Container.Callback.SAVED
|
Yenileme isteği, yerel olarak kaydedilmiş bir kapsayıcıyı yüklüyor. |
Container.Callback.NETWORK
|
Yenileme isteği, ağ üzerinden bir kapsayıcı yüklüyor. |
RefreshFailure
| Değer | Açıklama |
|---|---|
Container.Callback.NO_SAVED_CONTAINER
|
Kayıtlı kapsayıcı yok. |
Container.Callback.IO_ERROR
|
Bir G/Ç hatası nedeniyle kapsayıcı yenilenemedi. |
Container.Callback.NO_NETWORK
|
Kullanılabilir ağ bağlantısı yok. |
Container.Callback.NETWORK_ERROR
|
Bir ağ hatası oluştu. |
Container.Callback.SERVER_ERROR
|
Sunucuda bir hata oluştu. |
Container.Callback.UNKNOWN_ERROR
|
Kategorize edilemeyen bir hata oluştu. |
Varsayılan Olmayan ve Yeni Kapsayıcıları Açma Yöntemleri
ContainerOpener, TagManager.openContainer() sınıfını sarmalar ve kapsayıcıları açmak için iki kolaylık yöntemi sunar: ContainerOpener.openContainer(..., Notifier notifier) ve ContainerOpener.openContainer(..., Long timeoutInMillis).
Bu yöntemlerin her biri, varsayılan olmayan veya yeni bir kapsayıcı isteyen bir numaralandırma alır.
OpenType.PREFER_NON_DEFAULT çoğu uygulama için önerilir ve belirli bir zaman aşımı süresi içinde, diskten veya ağdan, varsayılan olmayan ilk kullanılabilir kapsayıcıyı (bu kapsayıcı 12 saatten eski olsa bile) döndürmeye çalışır. Eski bir kayıtlı kapsayıcı döndürürse yeni bir kapsayıcı için eşzamansız bir ağ isteği de gönderir.
OpenType.PREFER_NON_DEFAULT kullanılırken başka bir kapsayıcı yoksa veya zaman aşımı süresi aşılırsa varsayılan bir kapsayıcı döndürülür.
OpenType.PREFER_FRESH, belirtilen zaman aşımı süresi içinde diskten veya ağdan yeni bir kapsayıcı döndürmeye çalışır.
Ağ bağlantısı yoksa ve/veya zaman aşımı süresi aşılırsa kaydedilmiş bir kapsayıcı döndürür.
Daha uzun bir istek süresinin kullanıcı deneyimini belirgin şekilde etkileyebileceği yerlerde (ör. kullanıcı arayüzü işaretleri veya görüntüleme dizeleri) OpenType.PREFER_FRESH kullanılması önerilmez. Ağ kapsayıcısı isteğini zorunlu kılmak için dilediğiniz zaman Container.refresh() da kullanabilirsiniz.
Bu kolaylık yöntemlerinin her ikisi de engellenmez.
ContainerOpener.openContainer(..., Long timeoutInMillis), ContainerOpener.ContainerFuture nesnesi döndürür. Bu nesnenin get yöntemi, yüklendiği anda Container döndürür (ancak o zamana kadar engellenir).
ContainerOpener.openContainer(..., Notifier notifier) yöntemi, kapsayıcı kullanılabilir olduğunda çağrılan tek bir geri çağırma alır. Bu geri çağırma, ana iş parçacığının engellenmesini önlemek için kullanılabilir.
Her iki yöntemin de varsayılan zaman aşımı süresi 2000 milisaniyedir.
Kuralları kullanarak çalışma zamanında makroları değerlendirme
Kapsayıcılar, kuralları kullanarak çalışma zamanında değerleri değerlendirebilir. Kurallar; cihaz dili, platform veya diğer makro değerleri gibi ölçütlere dayalı olabilir. Örneğin, çalışma zamanında cihazın diline göre yerelleştirilmiş bir görüntüleme dizesi seçmek için kurallar kullanılabilir. Bu, aşağıdaki kural kullanılarak yapılandırılabilir:
Ardından her dil için değer toplama makroları oluşturabilir ve uygun dil kodunu ekleyerek bu kuralı her makroya ekleyebilirsiniz. Bu kapsayıcı yayınlandığında, uygulamanız çalışma zamanında kullanıcının cihazının diline bağlı olarak yerelleştirilmiş görüntüleme dizelerini gösterebilir.
Varsayılan kapsayıcınızın kurallara ihtiyacı varsa varsayılan kapsayıcınız olarak ikili kapsayıcı dosyası kullanmanız gerektiğini unutmayın.
Kuralları yapılandırma hakkında daha fazla bilgi (Yardım Merkezi)
İkili Varsayılan Kapsayıcı Dosyaları
Kural gerektiren varsayılan kapsayıcılar, varsayılan kapsayıcı olarak JSON dosyası yerine ikili kapsayıcı dosyası kullanmalıdır. İkili kapsayıcılar, Google Etiket Yöneticisi kurallarıyla çalışma zamanında makro değerlerini belirleme desteği sunarken JSON dosyaları bu desteği sunmaz.
İkili kapsayıcı dosyaları Google Etiket Yöneticisi web arayüzünden indirilebilir ve projenizin /assets/tagmanager/ klasörüne eklenmelidir. Bu dosyalar şu kalıbı izlemelidir: /assets/tagmanager/GTM-XXXX. Burada dosya adı, kapsayıcı kimliğinizi temsil eder.
Hem JSON dosyası hem de ikili kapsayıcı dosyası varsa SDK, varsayılan kapsayıcı olarak ikili kapsayıcı dosyasını kullanır.
İşlev Çağrısı Makrolarını Kullanma
İşlev çağrısı makroları, uygulamanızdaki belirli bir işlevin döndürdüğü değere ayarlanmış makrolardır. İşlev Çağrısı Makroları, çalışma zamanı değerlerini Google Etiket Yöneticisi kurallarınıza dahil etmek için kullanılabilir. Örneğin, bir cihazın yapılandırılmış diline ve para birimine göre kullanıcıya hangi fiyatın gösterileceğini çalışma zamanında belirleyebilirsiniz.
İşlev çağrısı makrosu yapılandırmak için:
- Google Etiket Yöneticisi web arayüzünde işlev çağrısı makrosunu tanımlayın. Bağımsız değişkenler isteğe bağlı olarak anahtar/değer çiftleri şeklinde yapılandırılabilir.
FunctionCallMacroHandlerve Google Etiket Yöneticisi web arayüzünde yapılandırdığınız işlev adını kullanarak uygulamanızda birContainer.registerFunctionCallMacroHandler()kaydedin vegetValue()yöntemini geçersiz kılın:/** * Registers a function call macro handler. * * @param functionName The function name field, as defined in the Google Tag * Manager web interface. */ mContainer.registerFunctionCallMacroHandler(functionName, new FunctionCallMacroHandler() { /** * This code will execute when any custom macro's rule(s) evaluate to true. * The code should check the functionName and process accordingly. * * @param functionName Corresponds to the function name field defined * in the Google Tag Manager web interface. * @param parameters An optional map of parameters * as defined in the Google Tag Manager web interface. */ @Override public Object getValue(String functionName, Map<String, Object> parameters)) { if (functionName.equals("myConfiguredFunctionName")) { // Process and return the calculated value of this macro accordingly. return macro_value } return null; } });
İşlev Çağrısı Etiketlerini Kullanma
İşlev Çağrısı Etiketleri, bir etkinlik veri katmanına aktarıldığında ve etiket kuralları true olarak değerlendirildiğinde önceden kayıtlı işlevlerin yürütülmesini sağlar.
İşlev çağrısı etiketini yapılandırmak için:
- Google Etiket Yöneticisi web arayüzünde işlev çağrısı etiketini tanımlayın. Bağımsız değişkenler isteğe bağlı olarak anahtar/değer çiftleri şeklinde yapılandırılabilir.
Container.registerFunctionCallTagHandler()kullanarak uygulamanıza bir işlev çağrısı etiket işleyicisi kaydedin:/** * Register a function call tag handler. * * @param functionName The function name, which corresponds to the function name field * Google Tag Manager web interface. */ mContainer.registerFunctionCallTagHandler(functionName, new FunctionCallTagHandler() { /** * This method will be called when any custom tag's rule(s) evaluates to true. * The code should check the functionName and process accordingly. * * @param functionName The functionName passed to the functionCallTagHandler. * @param parameters An optional map of parameters as defined in the Google * Tag Manager web interface. */ @Override public void execute(String functionName, Map<String, Object> parameters) { if (functionName.equals("myConfiguredFunctionName")) { // Process accordingly. } } });
Özel Yenileme Dönemi Ayarlama
Google Etiket Yöneticisi SDK'sı, mevcut kapsayıcının yaşı 12 saati aşarsa yeni bir kapsayıcı almaya çalışır. Özel bir kapsayıcı yenileme süresi ayarlamak için aşağıdaki örnekte olduğu gibi Timer kullanın:
timer.scheduleTask(new TimerTask() { @Override public void run() { mContainer.refresh(); } }, delay, <new_period_in milliseconds>);
Logger ile hata ayıklama
Google Etiket Yöneticisi SDK'sı, varsayılan olarak hataları ve uyarıları günlüklere yazdırır.
Daha ayrıntılı günlük kaydını etkinleştirmek, hata ayıklama için yararlı olabilir. Bu işlem, aşağıdaki örnekte olduğu gibi TagManager.setLogger ile kendi Logger öğenizi uygulayarak yapılabilir:
TagManager tagManager = TagManager.getInstance(this); tagManager.setLogger(new Logger() { final String TAG = "myGtmLogger"; // Log output with verbosity level of DEBUG. @Override public void d(String arg0) { Log.d(TAG, arg0); } // Log exceptions when provided. @Override public void d(String arg0, Throwable arg1) { Log.d(TAG, arg0); arg1.printStackTrace(); } // Rest of the unimplemented Logger methods. });
Dilerseniz mevcut Logger'ın LogLevel değerini
TagManager.getLogger().setLogLevel(LogLevel)
kullanarak da ayarlayabilirsiniz.
Örnek:
// Change the LogLevel to INFO to enable logging at INFO and higher levels. TagManager tagManager = TagManager.getInstance(this); tagManager.getLogger().setLogLevel(LogLevel.INFO);