Remote Config'i programatik olarak değiştirme

Bu dokümanda, Remote Config şablonu olarak bilinen JSON biçimli parametre ve koşullar grubunu programatik olarak nasıl okuyabileceğiniz ve değiştirebileceğiniz açıklanmaktadır. Bu sayede, arka uçta istemci uygulamasının istemci kitaplığını kullanarak getirebileceği şablon değişiklikleri yapabilirsiniz.

Remote Config REST API'yi veya bu kılavuzda açıklanan Admin SDK'leri kullanarak Remote Config değişikliklerini doğrudan kendi süreçlerinize entegre etmek için şablonu Firebase konsolunda yönetmeyi atlayabilirsiniz. Örneğin, Remote Config arka uç API'leri ile şunları yapabilirsiniz:

• Remote Config güncellemelerini planlama. API çağrılarını bir cron işi ile birlikte kullanarak Remote Config değerlerini düzenli bir programda değiştirebilirsiniz.
• Kendi özel sisteminizden Firebase Remote Config'e verimli bir şekilde geçiş yapmak için yapılandırma değerlerini toplu olarak içe aktarın.

• Remote Config'u Cloud Functions for Firebase ile birlikte kullanarak, uygulamanızdaki değerleri sunucu tarafında gerçekleşen etkinliklere göre değiştirin. Örneğin, uygulamanızda yeni bir özelliği tanıtmak için Remote Config'ü kullanabilir ve yeterli sayıda kullanıcının yeni özellikle etkileşime geçtiğini tespit ettiğinizde bu tanıtımı otomatik olarak devre dışı bırakabilirsiniz.

  

Bu kılavuzun aşağıdaki bölümlerinde, Remote Config arka uç API'leriyle yapabileceğiniz işlemler açıklanmaktadır. Bu görevleri REST API üzerinden gerçekleştiren bazı kodları incelemek için aşağıdaki örnek uygulamalardan birine bakın:

• Firebase Remote Config REST API Java Hızlı Başlangıç Kılavuzu
• Firebase Remote Config REST API Node.js Hızlı Başlangıç
• Firebase Remote Config REST API Python Hızlı Başlangıç Kılavuzu

Firebase Admin SDK'sını kullanarak Remote Config'i değiştirme

Admin SDK, ayrıcalıklı ortamlardan Firebase ile etkileşime geçmenize olanak tanıyan bir sunucu kitaplığı grubudur. Admin SDK, Remote Config'te güncelleme yapmanın yanı sıra Firebase kimlik jetonlarının oluşturulmasını ve doğrulanmasını, Realtime Database'den veri okumayı ve yazma işlemlerini vb. sağlar. Admin SDK ön koşulları ve kurulum hakkında daha fazla bilgi edinmek için Firebase Admin SDK'sını sunucunuza ekleme başlıklı makaleyi inceleyin.

Tipik bir Remote Config akışında, mevcut şablonu alabilir, parametrelerden veya parametre gruplarından ve koşullardan bazılarını değiştirebilir, şablonu doğrulayabilir ve ardından yayınlayabilirsiniz. Bu API çağrılarını yapmadan önce SDK'dan gelen istekleri yetkilendirmeniz gerekir.

SDK'yı başlatma ve API isteklerini yetkilendirme

Admin SDK parametresi olmadan başlattığınızda SDK, Google Uygulama Varsayılan Kimlik Bilgileri'ni kullanır ve seçenekleri FIREBASE_CONFIG ortam değişkeninden okur. FIREBASE_CONFIG değişkeninin içeriği { ile başlıyorsa JSON nesnesi olarak ayrıştırılır. Aksi takdirde SDK, dizenin seçenekleri içeren bir JSON dosyasının adı olduğunu varsayar.

Örneğin:

const admin = require('firebase-admin');
admin.initializeApp();

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

Mevcut Remote Config şablonunu alma

Remote Config şablonlarıyla çalışırken, şablonların sürümlere sahip olduğunu ve her bir sürümün oluşturulduğu andan güncellemeyle değiştirdiğiniz ana kadar sınırlı bir kullanım süresine sahip olduğunu unutmayın. Bu süre 90 gündür ve toplamda 300 sürüm saklayabilirsiniz. Daha fazla bilgi için Şablonlar ve Sürüm Yönetimi bölümüne bakın.

Remote Config şablonunun geçerli etkin sürümünü JSON biçiminde almak için arka uç API'lerini kullanabilirsiniz.

A/B Testing denemesinde özellikle varyant olarak oluşturulan parametreler ve parametre değerleri, dışa aktarılan şablonlara dahil edilmez.

Şablonu almak için:

function getTemplate() {
  var config = admin.remoteConfig();
  config.getTemplate()
      .then(function (template) {
        console.log('ETag from server: ' + template.etag);
        var templateStr = JSON.stringify(template);
        fs.writeFileSync('config.json', templateStr);
      })
      .catch(function (err) {
        console.error('Unable to get template');
        console.error(err);
      });
}

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

Remote Config parametrelerini değiştirme

Remote Config parametrelerini ve parametre gruplarını programatik olarak değiştirebilir ve ekleyebilirsiniz. Örneğin, "new_menu" adlı mevcut bir parametre grubuna sezonluk bilgilerin görüntülenmesini kontrol etmek için bir parametre ekleyebilirsiniz:

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

template.getParameterGroups().get("new_menu").getParameters()
        .put("spring_season", new Parameter()
                .setDefaultValue(ParameterValue.inAppDefault())
                .setDescription("spring season menu visibility.")
        );

API, yeni parametreler ve parametre grupları oluşturmanıza veya varsayılan değerleri, koşullu değerleri ve açıklamaları değiştirmenize olanak tanır. Her durumda, değişiklikleri yaptıktan sonra şablonu açıkça yayınlamanız gerekir.

Remote Config koşullarını değiştirme

Remote Config koşullarını ve koşullu değerleri programatik olarak değiştirebilir ve ekleyebilirsiniz. Örneğin, yeni bir koşul eklemek için:

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

Her durumda, değişiklikleri yaptıktan sonra şablonu açıkça yayınlamanız gerekir.

Remote Config arka uç API'leri, uygulamanızın davranışını ve görünümünü değiştirmek için kullanabileceğiniz çeşitli koşullar ve karşılaştırma operatörleri sağlar. Koşullar ve bu koşullar için desteklenen operatörler hakkında daha fazla bilgi edinmek için koşullu ifade referansı bölümüne bakın.

Remote Config şablonunu doğrulama

İsteğe bağlı olarak, güncellemelerinizi yayınlamadan önce doğrulayabilirsiniz.

function validateTemplate(template) {
  admin.remoteConfig().validateTemplate(template)
      .then(function (validatedTemplate) {
        // The template is valid and safe to use.
        console.log('Template was valid and safe to use');
      })
      .catch(function (err) {
        console.error('Template is invalid and cannot be published');
        console.error(err);
      });
}

try {
  Template validatedTemplate = FirebaseRemoteConfig.getInstance()
          .validateTemplateAsync(template).get();
  System.out.println("Template was valid and safe to use");
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Template is invalid and cannot be published");
    System.out.println(rcError.getMessage());
  }
}

Bu doğrulama işleminde, parametreler ve koşullar için yinelenen anahtarlar, geçersiz koşul adları veya var olmayan koşullar ya da yanlış biçimlendirilmiş e-etiketler gibi hatalar kontrol edilir. Örneğin, izin verilenden fazla anahtar (2.000) içeren bir istek, Param count too large hata mesajını döndürür.

Remote Config şablonunu yayınlama

Bir şablonu aldıktan ve istediğiniz güncellemelerle düzelttikten sonra yayınlayabilirsiniz. Bu bölümde açıklandığı şekilde bir şablon yayınladığınızda mevcut yapılandırma şablonunun tamamı güncellenen dosyayla değiştirilir ve yeni etkin şablona, değiştirilen şablondan bir sayı daha büyük bir sürüm numarası atanır.

Gerekirse önceki sürüme geri dönmek için REST API'yi kullanabilirsiniz. Güncellemelerde hata riskini azaltmak için yayınlamadan önce doğrulama yapabilirsiniz.

Remote Config kişiselleştirmeleri ve koşulları indirilen şablonlara dahil edilir. Bu nedenle, farklı bir projede yayınlamaya çalışırken aşağıdaki sınırlamalara dikkat etmeniz önemlidir:

• Kişiselleştirmeler projeden projeye aktarılamaz.

  Örneğin, projenizde kişiselleştirmeleri etkinleştirdiyseniz ve bir şablonu indirip düzenlediyseniz şablonu aynı projede yayınlayabilirsiniz ancak şablondaki kişiselleştirmeleri silmediğiniz sürece farklı bir projede yayınlayamazsınız.

• Koşullar projeden projeye aktarılabilir ancak belirli koşullu değerlerin (ör. uygulama kimlikleri veya kitleler) yayınlanmadan önce hedef projede mevcut olması gerektiğini unutmayın.

  Örneğin, iOS platform değerini belirten bir koşul kullanan bir Remote Config parametreniz varsa platform değerleri her proje için aynı olduğundan şablon başka bir projede yayınlanabilir. Ancak hedef projede bulunmayan belirli bir uygulama kimliğine veya kullanıcı kitlesine dayanan bir koşul içeriyorsa doğrulama başarısız olur.

• Yayınlamayı planladığınız şablon Google Analytics'e dayalı koşullar içeriyorsa Analytics hedef projede etkinleştirilmelidir.

function publishTemplate() {
  var config = admin.remoteConfig();
  var template = config.createTemplateFromJSON(
      fs.readFileSync('config.json', 'UTF8'));
  config.publishTemplate(template)
      .then(function (updatedTemplate) {
        console.log('Template has been published');
        console.log('ETag from server: ' + updatedTemplate.etag);
      })
      .catch(function (err) {
        console.error('Unable to publish template.');
        console.error(err);
      });
}

try {
  Template publishedTemplate = FirebaseRemoteConfig.getInstance()
          .publishTemplateAsync(template).get();
  System.out.println("Template has been published");
  // See the ETag of the published template.
  System.out.println("ETag from server: " + publishedTemplate.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Unable to publish template.");
    System.out.println(rcError.getMessage());
  }
}

REST API'yi kullanarak Remote Config'i değiştirme

Bu bölümde, https://firebaseremoteconfig.googleapis.com adresindeki Remote Config REST API'nin temel özellikleri açıklanmaktadır. Tüm ayrıntılar için API referansı bölümüne bakın.

API isteklerinin kimliğini doğrulamak ve yetkilendirmek için erişim jetonu alma

Firebase projeleri, Google hizmet hesaplarını destekler. Bu hesapları, uygulama sunucunuzdan veya güvenilir ortamınızdan Firebase sunucu API'lerini çağırmak için kullanabilirsiniz. Yerel olarak kod geliştiriyorsanız veya uygulamanızı şirket içinde dağıtıyorsanız sunucu isteklerine yetki vermek için bu hizmet hesabı aracılığıyla edinilen kimlik bilgilerini kullanabilirsiniz.

Bir hizmet hesabının kimliğini doğrulamak ve Firebase hizmetlerine erişmesi için yetkilendirmek üzere JSON biçiminde bir özel anahtar dosyası oluşturmanız gerekir.

Hizmet hesabınız için özel anahtar dosyası oluşturmak üzere:

1. Firebase konsolunda Ayarlar > Hizmet Hesapları'nı açın.

2. Yeni Gizli Anahtar Oluştur'u tıklayın, ardından Anahtar Oluştur'u tıklayarak onaylayın.

3. Anahtarı içeren JSON dosyasını güvenli bir şekilde saklayın.

Bir hizmet hesabı üzerinden yetki verirken uygulamanıza kimlik bilgilerini sağlama konusunda iki seçeneğiniz vardır. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlayabilir veya hizmet hesabı anahtarının yolunu kodda açıkça iletebilirsiniz. İlk seçenek daha güvenlidir ve kesinlikle önerilir.

Ortam değişkenini ayarlamak için:

GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini, hizmet hesabı anahtarınızı içeren JSON dosyasının dosya yoluna ayarlayın. Bu değişken yalnızca mevcut kabuk oturumunuz için geçerlidir. Bu nedenle, yeni bir oturum açarsanız değişkeni tekrar ayarlayın.

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Yukarıdaki adımları tamamladıktan sonra Uygulama Varsayılan Kimlik Bilgileri (ADC), kimlik bilgilerinizi dolaylı olarak belirleyebilir. Böylece, Google dışı ortamlarda test ederken veya çalıştırırken hizmet hesabı kimlik bilgilerini kullanabilirsiniz.

Kısa süreli bir OAuth 2.0 erişim jetonu almak için Firebase kimlik bilgilerinizi tercih ettiğiniz dildeki Google Auth Library ile birlikte kullanın:

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}
index.js

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
configure.py

public static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
FirebaseRemoteConfigSnippets.java

Erişim jetonunuzun süresi dolduktan sonra, güncellenmiş bir erişim jetonu almak için jeton yenileme yöntemi otomatik olarak çağrılır.

Remote Config'e erişim yetkisi vermek için https://www.googleapis.com/auth/firebase.remoteconfig kapsamını isteyin.

Remote Config şablonunu değiştirme

Remote Config şablonlarıyla çalışırken, şablonların sürümlere sahip olduğunu ve her bir sürümün oluşturulduğu andan güncellemeyle değiştirdiğiniz ana kadar sınırlı bir kullanım süresine sahip olduğunu unutmayın. Bu süre 90 gündür ve toplamda 300 sürüm saklayabilirsiniz. Daha fazla bilgi için Şablonlar ve Sürüm Yönetimi bölümüne bakın.

Mevcut Remote Config şablonunu alma

Remote Config şablonunun geçerli etkin sürümünü JSON biçiminde almak için arka uç API'lerini kullanabilirsiniz.

A/B Testing denemesinde özellikle varyant olarak oluşturulan parametreler ve parametre değerleri, dışa aktarılan şablonlara dahil edilmez.

Aşağıdaki komutları kullanın:

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

Remote Config şablonunu doğrulama

İsteğe bağlı olarak, güncellemelerinizi yayınlamadan önce doğrulayabilirsiniz. Yayın isteğinize ?validate_only=true URL parametresini ekleyerek şablon güncellemelerini doğrulayın. Yanıtta 200 durum kodu ve -0 son ekini içeren güncellenmiş bir etag, güncellemenizin başarıyla doğrulandığı anlamına gelir. 200 olmayan tüm yanıtlar, JSON verilerinin yayınlanmadan önce düzeltmeniz gereken hatalar içerdiğini gösterir.

Remote Config şablonunu güncelleme

Bir şablon aldıktan ve JSON içeriğini istediğiniz güncellemelerle düzelttikten sonra şablonu yayınlayabilirsiniz. Bu bölümde açıklandığı şekilde bir şablon yayınladığınızda mevcut yapılandırma şablonunun tamamı güncellenen dosyayla değiştirilir ve yeni etkin şablona, değiştirilen şablondan bir sayı daha büyük bir sürüm numarası atanır.

Gerekirse önceki sürüme geri dönmek için REST API'yi kullanabilirsiniz. Güncellemelerde hata riskini azaltmak için yayınlamadan önce doğrulama yapabilirsiniz.

Remote Config kişiselleştirmeleri ve koşulları indirilen şablonlara dahil edilir. Bu nedenle, farklı bir projede yayınlamaya çalışırken aşağıdaki sınırlamaları göz önünde bulundurmanız önemlidir:

• Kişiselleştirmeler projeden projeye aktarılamaz.

  Örneğin, projenizde kişiselleştirmeleri etkinleştirdiyseniz ve bir şablonu indirip düzenlediyseniz şablonu aynı projede yayınlayabilirsiniz ancak şablondaki kişiselleştirmeleri silmediğiniz sürece farklı bir projede yayınlayamazsınız.

• Koşullar projeden projeye aktarılabilir ancak belirli koşullu değerlerin (ör. uygulama kimlikleri veya kitleler) yayınlanmadan önce hedef projede mevcut olması gerektiğini unutmayın.

  Örneğin, iOS platform değerini belirten bir koşul kullanan bir Remote Config parametreniz varsa platform değerleri her proje için aynı olduğundan şablon başka bir projede yayınlanabilir. Ancak hedef projede bulunmayan belirli bir uygulama kimliğine veya kullanıcı kitlesine dayanan bir koşul içeriyorsa doğrulama başarısız olur.

• Yayınlamayı planladığınız şablon Google Analytics'e dayalı koşullar içeriyorsa Analytics hedef projede etkinleştirilmelidir.

curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -d @filename

Host: firebaseremoteconfig.googleapis.com
PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1
Content-Length: size
Content-Type: application/json; UTF8
Authorization: Bearer token
If-Match: expected ETag
Accept-Encoding: gzip
JSON_HERE

Remote Config koşullarını değiştirme

Remote Config koşullarını ve koşullu değerleri programatik olarak değiştirebilirsiniz. REST API ile, şablonu yayınlamadan önce koşulları değiştirmek için şablonu doğrudan düzenlemeniz gerekir.

{
  "conditions": [{
    "name": "android_english",
    "expression": "device.os == 'android' && device.country in ['us', 'uk']",
    "tagColor": "BLUE"
  }, {
    "name": "tenPercent",
    "expression": "percent <= 10",
    "tagColor": "BROWN"
  }],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "tenPercent": {
          "value": "Welcome to this new sample app"
        }
      },
      "description": "The sample app's welcome message"
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      },
      "conditionalValues": {
        "android_english": {
          "value": "true"
        }
      },
      "description": "Whether the welcome message should be displayed in all capital letters."
    }
  }
}

Yukarıdaki değişiklikler önce bir dizi koşulu, ardından her parametre için varsayılan değerleri ve koşula dayalı parametre (koşullu değerler) değerlerini tanımlar. Ayrıca her öğe için isteğe bağlı bir açıklama da eklenir. Kod yorumları gibi bu açıklamalar geliştiriciler tarafından kullanılır ve uygulamada gösterilmez. Sürüm kontrolü amacıyla bir ETag da sağlanır.

Remote Config arka uç API'leri, uygulamanızın davranışını ve görünümünü değiştirmek için kullanabileceğiniz çeşitli koşullar ve karşılaştırma operatörleri sağlar. Koşullar ve bu koşullar için desteklenen operatörler hakkında daha fazla bilgi edinmek için koşullu ifade referansı bölümüne bakın.

HTTP hata kodları

200 durum kodu, Remote Config şablonunun (projenin parametreleri, değerleri ve koşulları) güncellendiği ve artık bu projeyi kullanan uygulamalar tarafından kullanılabileceği anlamına gelir. Diğer durum kodları, daha önce var olan Remote Config şablonunun hâlâ geçerli olduğunu gösterir.

Şablonunuza güncelleme gönderdikten sonra, değişikliklerinizin beklendiği gibi göründüğünü doğrulamak için Firebase konsoluna gidin. Koşulların sıralaması, nasıl değerlendirildiklerini etkilediği için bu durum kritiktir (true değerini değerlendiren ilk koşul geçerli olur).

ETag kullanımı ve zorunlu güncellemeler

Remote Config REST API, yarış koşullarını ve kaynaklarda çakışan güncellemeleri önlemek için varlık etiketi (ETag) kullanır. ETag'ler hakkında daha fazla bilgi edinmek için ETag - HTTP başlıklı makaleyi inceleyin.

Google, REST API için en son GET komutu tarafından sağlanan ETag değerini önbelleğe almanızı ve PUT komutları verirken bu ETag değerini If-Match istek üstbilgisinde kullanmanızı önerir. PUT komutunuz HTTPS durum kodu 409 ile sonuçlanırsa sonraki PUT komutunuzda kullanabileceğiniz yeni bir ETag ve şablon edinmek için yeni bir GET komutu göndermeniz gerekir.

Remote Config şablonunu aşağıdaki şekilde güncellenmeye zorlayarak ETag'i ve sağladığı korumayı atlayabilirsiniz: If-Match: * Ancak birden fazla istemci Remote Config şablonunu güncelliyorsa Remote Config şablonunuzdaki güncellemelerin kaybolmasına neden olabileceğinden bu yaklaşım önerilmez. Bu tür bir çakışma, API'yi kullanan birden fazla istemci veya API istemcileri ile Firebase konsol kullanıcılarından gelen çakışan güncellemeler nedeniyle ortaya çıkabilir.

Remote Config şablon sürümlerini yönetmeyle ilgili yardım için Remote Config şablonları ve sürüm oluşturma başlıklı makaleyi inceleyin.