Android v4 - Başlarken

Giriş

Google Etiket Yöneticisi, geliştiricilerin uygulama ikili programlarını yeniden oluşturup uygulama pazarlarına yeniden göndermek zorunda kalmadan Google Etiket Yöneticisi arayüzünü kullanarak mobil uygulamalarındaki yapılandırma değerlerini değiştirmesine olanak tanır.

Bu özellik, uygulamanızda gelecekte değiştirmeniz gerekebilecek yapılandırma değerlerini veya işaretlerini yönetmek açısından yararlı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
  • Çeşitli oyun ayarları

Yapılandırma değerleri, çalışma zamanında kurallar kullanılarak da değerlendirilebilir. Böylece, aşağıdaki gibi dinamik yapılandırmalar etkinleştirilir:

  • Reklam banner boyutunu belirlemek için ekran boyutunu kullanma
  • Kullanıcı arayüzü öğelerini yapılandırmak için dil ve konum kullanma

Google TagManager, uygulamalarda izleme etiketlerinin ve piksellerin 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 verebilirler.

Başlamadan önce

Bu başlangıç kılavuzuna başlamadan önce aşağıdaki adımları uygulayın:

Bu adımları tamamladıktan sonra, bu kılavuzun geri kalanında Google Etiket Yöneticisi'ni Android uygulamanızda nasıl yapılandırıp kullanacağınızı öğreneceksiniz.

Başlayın

Bu Başlangıç Kılavuzu'ndaki adımları uyguladıktan sonra:

Bu kılavuzda, Google Play Hizmetleri SDK'sına dahil olan Cute Animals örnek uygulamadan kod snippet'leri kullanılmaktadır. Bu projenin tam kaynağını şurada bulabilirsiniz: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

1. Google Etiket Yöneticisi'ni Projenize Ekleme

Projenize Google Etiket Yöneticisi'ni eklemek için:

  1. Google Play Hizmetleri SDK'sını ayarlayın.
  2. Android Studio dışında bir IDE kullanıyorsanız AndroidManifest.xml dosyasına aşağıdaki izinleri ekleyin:
    <!-- For TagManager SDK -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
  3. InstallReferrerReceiver mülkünün kampanya verilerini ayarlamak üzere Google Analytics alıcısını çağırmasını sağlamak için AndroidManifest.xml dosyasına aşağıdaki kodu ekleyin:
    <!-- Used for install referrer tracking-->
    <service android:name="com.google.android.gms.tagmanager.InstallReferrerService" />
    <receiver
      android:name="com.google.android.gms.tagmanager.InstallReferrerReceiver"
      android:exported="true">
      <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
      </intent-filter>
    </receiver>
    

2. Projenize Varsayılan Kapsayıcı Dosyası Ekleme

Google Etiket Yöneticisi, uygulamanız ilk kez çalıştırıldığında varsayılan bir kapsayıcı kullanır. Uygulama, ağ üzerinden yeni bir kapsayıcı alır almaz varsayılan kapsayıcı artık kullanılamaz.

Varsayılan kapsayıcı ikili programını indirmek ve uygulamanıza eklemek için:

  1. Google Etiket Yöneticisi web arayüzünde oturum açın.
  2. İndirmek istediğiniz kapsayıcının Sürüm'ünü seçin.
  3. Kapsayıcı ikili programını almak için İndir düğmesini tıklayın.
  4. İndirilen kapsayıcı ikili dosyayı projenize ham kaynak olarak ekleyin.
    1. <project-root>/res/ altında raw alt klasörü yoksa oluşturun.
    2. Gerekirse kapsayıcı ikili dosyayı yeniden adlandırın. Yalnızca küçük harf, rakam ve alt çizgilerden oluşur.
    3. Kapsayıcı ikili dosyayı <project-root>/res/raw klasörüne kopyalayın.

İkili dosyanın kullanılması önerilir ancak kapsayıcınız kural veya etiket içermiyorsa basit bir JSON dosyası kullanmayı tercih edebilirsiniz.

3. Google Etiket Yöneticisi başlatılıyor

Uygulamanızda Google Etiket Yöneticisi'ni başlatmak için:

  1. TagManager teklisini alın:
    TagManager tagManager = TagManager.getInstance(this);
    
  2. Kapsayıcı yükleme isteğinde bulunmak için TagManager teklisini kullanın ve bir Google Etiket Yöneticisi kapsayıcı kimliğinin yanı sıra varsayılan kapsayıcı dosyanızı belirtin. Kapsayıcı kimliği büyük harfle yazılmalı ve Google Etiket Yöneticisi web arayüzündeki kapsayıcı kimliğiyle tam olarak eşleşmelidir. loadContainerPreferNonDefault() çağrısı engellenmiyor ve PendingResult döndürüyor:
    PendingResult<ContainerHolder> pending =
            tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
            R.raw.defaultcontainer_binary);
    
  3. Yükleme işlemi tamamlandıktan veya zaman aşımına uğradıktan sonra ContainerHolder öğesini döndürmek için bir ResultCallback kullanın:
    // The onResult method will be called as soon as one of the following happens:
    //     1. a saved container is loaded
    //     2. if there is no saved container, a network container is loaded
    //     3. the 2-second timeout occurs
    pending.setResultCallback(new ResultCallback<ContainerHolder>() {
        @Override
        public void onResult(ContainerHolder containerHolder) {
            ContainerHolderSingleton.setContainerHolder(containerHolder);
            Container container = containerHolder.getContainer();
            if (!containerHolder.getStatus().isSuccess()) {
                Log.e("CuteAnimals", "failure loading container");
                displayErrorToUser(R.string.load_error);
                return;
            }
            ContainerLoadedCallback.registerCallbacksForContainer(container);
            containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
            startMainActivity();
        }
    }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
    

    ContainerHolder Singleton Oluşturma

    Uygulamanızın her çalıştırılması için yalnızca bir ContainerHolder örneği sağlamalısınız. Bu nedenle, yukarıdaki örnekte ContainerHolder örneğine erişimi yönetmek için ContainerHolderSingleton yardımcı program sınıfı kullanılmaktadır. ContainerHolderSingleton sınıfı şu şekilde görünür:

    package com.google.android.tagmanager.examples.cuteanimals;
    
    import com.google.android.gms.tagmanager.ContainerHolder;
    
    /**
     * Singleton to hold the GTM Container (since it should be only created once
     * per run of the app).
     */
    public class ContainerHolderSingleton {
        private static ContainerHolder containerHolder;
    
        /**
         * Utility class; don't instantiate.
         */
        private ContainerHolderSingleton() {
        }
    
        public static ContainerHolder getContainerHolder() {
            return containerHolder;
        }
    
        public static void setContainerHolder(ContainerHolder c) {
            containerHolder = c;
        }
    }
    
    

4. Kapsayıcıdan Yapılandırma Değerlerini Alma

Kapsayıcı yüklendikten sonra, Container.get<type>() yöntemlerinden herhangi birini kullanarak yapılandırma değerlerini alabilirsiniz. Yapılandırma değerleri, Google Etiket Yöneticisi'nin değer koleksiyonu değişkenleri kullanılarak tanımlanır. Örneğin, aşağıdaki yöntem, bir kullanıcı arayüzü öğesi için kullanmaya karar verdiğimiz en son rengi alır ve tam sayı olarak döndürür:

/**
 * Returns an integer representing a color.
 */
private int getColor(String key) {
    return colorFromColorName(containerHolder.getContainer().getString(key));
}

Bu kod, renk adını kapsayıcıdan almak için iki şey yapar:

  1. ContainerHolder.getContainer() kullanarak ContainerHolder öğesinden Container alır.
  2. Google Etiket Yöneticisi web arayüzünde anahtarı ve değeri tanımladığınız Container.getString(key) aracını kullanarak renk değerini alır.

5. Etkinlikleri ve Değerleri dataLayer'a Aktarma

Google Etiket Yöneticisi ayrıca, uygulamanızın diğer bölümlerinde okunabilecek veya Google Etiket Yöneticisi web arayüzünde yapılandırdığınız etiketleri tetiklemek için kullanılabilecek bilgileri iletebileceğiniz bir dataLayer sağlar.

Değerleri dataLayer'a Aktarma

dataLayer, uygulamanızın diğer bölümlerinde kullanmak isteyebileceğiniz anahtar/değer çiftlerini depolamak için veya Google Etiket Yöneticisi etiketlerine girdi olarak kullanabileceğiniz bir kalıcılık katmanı sağlar.

dataLayer öğesine değer aktarmak için şu kalıbı uygulayın:

  1. DataLayer teklisini alın:
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
    
  2. Etkinliği DataLayer.push() kullanarak aktarın:
    // Put the image_name into the data layer for future use.
    TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);
    

dataLayer öğesinden bir değer almak için DataLayer.get(key) işlevini kullanın.

Etkinlikleri dataLayer'a Aktarma

Etkinliklerin dataLayer öğesine aktarılması, uygulama kodunuzu bu etkinliklere yanıt olarak tetiklemek isteyebileceğiniz etiketlerden ayırmanıza olanak tanır.

Örneğin, Google Analytics ekran görüntüleme izleme çağrılarını uygulamanıza sabit olarak kodlamak yerine, ekran etkinliklerini dataLayer öğesine aktarabilir ve izleme etiketlerinizi Google Etiket Yöneticisi web arayüzü aracılığıyla tanımlayabilirsiniz. Bu size, uygulama kodunuzu güncellemeden söz konusu etiketi değiştirme veya ekran etkinliklerine yanıt veren başka etiketler ekleme esnekliği sunar.

dataLayer platformuna bir etkinlik aktarmak için şu düzeni uygulayın:

  1. DataLayer teklisini alın:
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
    
  2. Etkinliği DataLayer.pushEvent() kullanarak aktarın:
    dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
    

    DataLayer.mapOf(), etkinlik aktarılırken dataLayer öğesini güncelleyecek bir anahtar/değer çifti eşlemesini kolayca oluşturmak için kullanabileceğiniz bir yardımcı program yöntemidir.

6. Önizleme, Hata Ayıklama ve Yayınlama

Kapsayıcınızın bir sürümünü yayınlamadan önce, istenen şekilde çalıştığından emin olmak için önizlemek isteyebilirsiniz. Google Etiket Yöneticisi, web arayüzünde bağlantılar ve QR kodları oluşturarak ve bunları uygulamanızı açmak için kullanarak kapsayıcınızın sürümlerini önizleme olanağı sunar. Beklenmedik davranışlarda hata ayıklamak için ayrıntılı günlük kaydı modunu da etkinleştirebilirsiniz.

Önizleniyor

Kapsayıcınızın bir sürümünü önizlemek için aşağıdaki adımları uygulayın:

  1. AndroidManifest dosyanıza bu önizleme Activity ekleniyor:
    <!--  Add preview activity. -->
    <activity
        android:name="com.google.android.gms.tagmanager.PreviewActivity"
        android:label="@string/app_name"
        android:noHistory="true">  <!-- optional, removes the previewActivity from the activity stack. -->
        <intent-filter>
          <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE"/>
        </intent-filter>
    </activity>
    

    Bu satırı, uygulamanızın paket adını içerecek şekilde değiştirdiğinizden emin olun:

    <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
    
  2. Google Etiket Yöneticisi web arayüzünde önizleme bağlantısı oluşturun
    1. Google Etiket Yöneticisi'nde oturum açın.
    2. Önizlemek için kapsayıcı sürümünü seçin
    3. Önizleme düğmesini tıklayın
    4. Uygulamanızın paket adını girin ve Önizlemeyi başlatma bağlantısı oluştur'u tıklayın.
  3. Uygulamanızı başlatmak için oluşturulan bağlantıyı veya QR kodunu kullanın
  4. Web arayüzündeki Önizlemeyi sonlandır bağlantısı oluştur seçeneği ile oluşturulan bir bağlantıyı izleyerek önizleme modundan çıkabilirsiniz.

Hata ayıklama

Kapsayıcı uygulamanızla ilgili sorunları gidermeniz gerekiyorsa TagManager.setVerboseLoggingEnabled(true) çağrısı yaparak ayrıntılı günlük kaydını etkinleştirin:

// Modify the log level of the logger to print out not only
// warning and error messages, but also verbose, debug, info messages.
tagManager.setVerboseLoggingEnabled(true);

Yayınlama

Kapsayıcınızı önizledikten ve beklendiği gibi çalıştığını doğruladıktan sonra kapsayıcınızı yayınlayabilirsiniz. Kullanıcılar kapsayıcıları yenilendiğinde, kapsayıcı yapılandırma değerleriniz, etiketleriniz ve etkinlikleriniz yayınlanır. Kapsayıcıları yenileme hakkında daha fazla bilgi edinin.

Gelişmiş Yapılandırma

Aşağıdaki bölümlerde, Google Etiket Yöneticisi uygulamanızı daha da özelleştirmek için kullanmak istediğiniz gelişmiş yapılandırma seçenekleri açıklanmaktadır.

Kapsayıcıyı Yenileme

Varsayılan olarak, kapsayıcınız 12 saatte bir yenilenmeye uygun hale gelir. Container'ı manuel olarak yenilemek için ContainerHolder.refresh() değerini kullanın:

ContainerHolderSingleton.getContainerHolder().refresh();

Bu, hemen döndürülmeyen eşzamansız bir çağrıdır. Ağ trafiğini azaltmak için refresh() yalnızca 15 dakikada bir çağrılabilir. Aksi takdirde hiçbir işlem yapılmaz.