شروع به کار با «پیکربندی از دور» در iOS

می‌توانید از Firebase Remote Config برای تعریف پارامترها در برنامه‌تان و به‌روزرسانی مقادیر آن‌ها در فضای ابری استفاده کنید، که به شما امکان می‌دهد ظاهر و رفتار برنامه‌تان را بدون توزیع به‌روزرسانی برنامه تغییر دهید. این راهنما شما را با مراحل شروع به کار آشنا می‌کند و چند کد نمونه ارائه می‌دهد که همه آن‌ها برای شبیه‌سازی یا بارگیری از مخزن GitHub firebase/quickstart-ios دردسترس هستند.

مرحله ۱: افزودن Remote Config به برنامه

1. اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه Apple خود اضافه کنید.

2. برای Remote Config، Google Analytics برای هدف‌یابی شرطی نمونه‌های برنامه به دارایی‌های کاربر و مخاطبان لازم است. مطمئن شوید که Google Analytics را در پروژه‌تان فعال کرده‌اید.

3. شیء تک‌قلو Remote Config را همان‌طور که در مثال زیر نشان داده شده است ایجاد کنید:

   Swift

   let remoteConfig = RemoteConfig.remoteConfig()
   let settings = RemoteConfigSettings()
   settings.minimumFetchInterval = 0
   RemoteConfig.remoteConfig().configSettings = settings
   MigratedSnippets.swift

   Objective-C

   FIRRemoteConfig *remoteConfig = [FIRRemoteConfig remoteConfig];
   FIRRemoteConfigSettings *remoteConfigSettings = [[FIRRemoteConfigSettings alloc] init];
   remoteConfigSettings.minimumFetchInterval = 0;
   remoteConfig.configSettings = remoteConfigSettings;
   ObjCMigratedSnippets.m

این شیء برای ذخیره کردن مقادیر پارامتر پیش‌فرض درون‌برنامه، واکشی مقادیر پارامتر به‌روزشده از پسای Remote Config، و کنترل زمان دردسترس قرار گرفتن مقادیر واکشی‌شده برای برنامه شما استفاده می‌شود.

درطول توسعه، توصیه می‌شود حداقل فاصله واکشی نسبتاً کمی تنظیم کنید. برای اطلاعات بیشتر، محدود کردن نرخ را ببینید.

مرحله ۲: تنظیم مقادیر پارامتر پیش‌فرض درون‌برنامه

می‌توانید مقادیر پارامتر پیش‌فرض درون‌برنامه را در شیء Remote Config تنظیم کنید تا برنامه‌تان قبل‌از اتصال به باطن Remote Config طبق انتظار رفتار کند و اگر هیچ مقداری در باطن تنظیم نشده باشد، مقادیر پیش‌فرض دردسترس باشند.

1. مجموعه‌ای از نام‌های پارامتر و مقادیر پیش‌فرض پارامتر را بااستفاده از NSDictionary شیء یا فایل plist تعریف کنید.

   اگر قبلاً مقادیر پارامترهای باطن Remote Config را پیکربندی کرده‌اید، می‌توانید فایل plist تولیدشده را که شامل همه مقادیر پیش‌فرض است بارگیری کنید و آن را در پروژه Xcode خود ذخیره کنید.

   REST (انتقال بازنمودی وضعیت)

   curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=PLIST -o RemoteConfigDefaults.plist
   

   می‌توانید با اجرای فرمان زیر بااستفاده از Google Cloud CLI یا Cloud Shell، رمزیاب دارنده تولید کنید:

   gcloud auth print-access-token
   

   این کد کوتاه مدت است، بنابراین اگر خطای اصالت‌سنجی دریافت کردید، ممکن است لازم باشد آن را دوباره تولید کنید.

   کنسول Firebase

   1. در کنسول Firebase، به DevOps و تعامل > پیکربندی از راه دور > صفحه پارامترها بروید.

   2. more_vert منو را باز کنید، و بارگیری مقادیر پیش‌فرض را انتخاب کنید.

   3. وقتی درخواست شد، plist.برای iOS را فعال کنید، سپس روی بارگیری فایل کلیک کنید.

2. این مقادیر را بااستفاده از setDefaults: به شیء Remote Config اضافه کنید. مثال زیر مقادیر پیش‌فرض درون‌برنامه را از فایل plist تنظیم می‌کند:

   Swift

   RemoteConfig.remoteConfig().setDefaults(fromPlist: "RemoteConfigDefaults")
   MigratedSnippets.swift

   Objective-C

   [remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];
   ObjCMigratedSnippets.m

مرحله ۳: دریافت مقادیر پارامتر برای استفاده در برنامه

اکنون می‌توانید مقادیر پارامتر را از شیء Remote Config دریافت کنید. اگر بعداً مقادیری را در پسای Remote Config تنظیم کنید، آن‌ها را واکشی کنید، و سپس آن‌ها را فعال کنید، آن مقادیر برای برنامه‌تان دردسترس خواهند بود. درغیراین‌صورت، مقادیر پارامتر درون‌برنامه را که بااستفاده از setDefaults: پیکربندی شده‌اند دریافت می‌کنید. برای دریافت این مقادیر، روش configValueForKey: را فراخوانی کنید و کلید پارامتر را به‌عنوان آرگومان ارائه دهید.

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a parameter value using configValueForKey
let welcomeMessageValue = remoteConfig.configValue(forKey: "welcome_message")
let welcomeMessage = welcomeMessageValue.stringValue

let featureFlagValue = remoteConfig.configValue(forKey: "new_feature_flag")
let isFeatureEnabled = featureFlagValue.boolValue

روش خواناتر و راحت‌تر برای دسترسی به این مقادیر در Swift ازطریق نماد زیرنویس Swift است:

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a string parameter value
let welcomeMessage = remoteConfig["welcome_message"].stringValue

// Retrieve a boolean parameter value
let isFeatureEnabled = remoteConfig["new_feature_flag"].boolValue

// Retrieve a number parameter value
let maxItemCount = remoteConfig["max_items"].numberValue.intValue

استفاده از Codable برای پیکربندی ایمن تایپی

برای پیکربندی‌های پیچیده‌تر، می‌توانید از پروتکل Codable Swift برای رمزگشایی داده‌های ساختاریافته از Remote Config استفاده کنید. این کار مدیریت پیکربندی ایمن ازنظر نوع را فراهم می‌کند و کار با اشیای پیچیده را ساده می‌کند.

// Define a Codable struct for your configuration
struct AppFeatureConfig: Codable {
  let isNewFeatureEnabled: Bool
  let maxUploadSize: Int
  let themeColors: [String: String]
}

// Fetch and decode the configuration
func configureAppFeatures() {
  let remoteConfig = RemoteConfig.remoteConfig()
  remoteConfig.fetchAndActivate { status, error in
    guard error == nil else { return }

    do {
      let featureConfig = try remoteConfig["app_feature_config"].decoded(asType: AppFeatureConfig.self)
      configureApp(with: featureConfig)
    } catch {
      // Handle decoding errors
      print("Failed to decode configuration: \(error)")
    }
  }
}

این روش به شما امکان می‌دهد:

• ساختارهای پیکربندی پیچیده را تعریف کنید.
• پیکربندی‌های JSON را به‌طور خودکار تجزیه می‌کند.
• هنگام دسترسی به مقادیر Remote Config، از ایمنی تایپی مطمئن شوید.
• کد تمیز و خوانایی برای مدیریت الگوهای ساختاریافته Remote Config ارائه بده.

استفاده از Property Wrappers برای پیکربندی اعلانی در SwiftUI

پوشاننده‌های ویژگی یکی از ویژگی‌های قدرتمند Swift هستند که به شما امکان می‌دهند رفتار سفارشی به اعلان‌های ویژگی اضافه کنید. در SwiftUI، از پوشاننده‌های ویژگی برای مدیریت وضعیت، اتصال‌ها، و دیگر رفتارهای ویژگی استفاده می‌شود. برای اطلاعات بیشتر، به راهنمای زبان Swift مراجعه کنید.

struct ContentView: View {
  @RemoteConfigProperty(key: "cardColor", fallback: "#f05138")
  var cardColor

  var body: some View {
    VStack {
      Text("Dynamic Configuration")
        .background(Color(hex: cardColor))
    }
    .onAppear {
      RemoteConfig.remoteConfig().fetchAndActivate()
    }
  }
}

وقتی می‌خواهید روشی اعلانی برای دسترسی به مقادیر Remote Config در SwiftUI داشته باشید، از پوشاننده ویژگی @RemoteConfigProperty استفاده کنید. این پوشاننده از مقادیر پیش‌فرض و مدیریت پیکربندی ساده‌شده پشتیبانی داخلی دارد.

مرحله ۴: تنظیم مقادیر پارامتر

بااستفاده از کنسول Firebase یا Remote Config میاناهای برنامه‌سازی کاربردی باطن، می‌توانید مقادیر پیش‌فرض باطن جدیدی ایجاد کنید که مقادیر درون‌برنامه را براساس منطق شرطی یا هدف‌یابی کاربر موردنظرتان لغو کند. این بخش شما را در مراحل کنسول Firebase برای ایجاد این مقادیر راهنمایی می‌کند.

1. در کنسول Firebase، به DevOps و تعامل > پیکربندی از راه دور > صفحه پارامترها بروید.

2. پارامترهایی با همان نام‌هایی که در برنامه‌تان تعریف کرده‌اید تعریف کنید. برای هر پارامتر، می‌توانید مقدار پیش‌فرضی تنظیم کنید (که درنهایت مقدار پیش‌فرض درون‌برنامه را لغو می‌کند) و همچنین می‌توانید مقادیر شرطی تنظیم کنید. برای کسب اطلاعات بیشتر، Remote Config پارامترها و شرایط را ببینید.

3. اگر از شرایط سیگنال سفارشی استفاده می‌کنید، مشخصه‌ها و مقادیر آن‌ها را تعریف کنید. مثال‌های زیر نحوه تعریف کردن شرط سیگنال سفارشی را نشان می‌دهد.

   Swift

       Task {
           let customSignals: [String: CustomSignalValue?] = [
           "city": .string("Tokyo"),
           "preferred_event_category": .string("sports")
         ]
   
         do {
           try await remoteConfig.setCustomSignals(customSignals)
           print("Custom signals set successfully!")
           } catch {
               print("Error setting custom signals: \(error)")
           }
     }

   Objective-C

       dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         NSDictionary *customSignals = @{
           @"city": @"Tokyo",
           @"preferred_event_category": @"sports"
         };
   
         [self.remoteConfig setCustomSignals:customSignals withCompletion:^(NSError * _Nullable error) {
             if (error) {
                 NSLog(@"Error setting custom signals: %@", error);
             } else {
                 NSLog(@"Custom signals set successfully!");
             }
       }];
   });

مرحله ۵: واکشی و فعال کردن مقادیر

برای واکشی مقادیر پارامتر از Remote Config، روش fetchWithCompletionHandler: یا fetchWithExpirationDuration:completionHandler: را فراخوانی کنید. هر مقداری که در پس‌بک تنظیم می‌کنید، واکشی می‌شود و در شیء Remote Config ذخیره می‌شود.

برای مواردی که می‌خواهید مقادیر را در یک تماس واکشی و فعال کنید، از fetchAndActivateWithCompletionHandler: استفاده کنید.

این مثال مقادیر را از پسای Remote Config واکشی می‌کند (نه مقادیر ذخیره‌شده در حافظه نهان) و activateWithCompletionHandler: را فراخوانی می‌کند تا آن‌ها را برای برنامه دردسترس قرار دهد:

remoteConfig.fetch { (status, error) -> Void in
  if status == .success {
    print("Config fetched!")
    remoteConfig.activate { changed, error in
      // ...
    }
  } else {
    print("Config not fetched")
    print("Error: \(error?.localizedDescription ?? "No error available.")")
  }
}
MigratedSnippets.swift

[remoteConfig fetchWithCompletionHandler:^(FIRRemoteConfigFetchStatus status, NSError *error) {
  if (status == FIRRemoteConfigFetchStatusSuccess) {
    NSLog(@"Config fetched!");
    [remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Activate error: %@", error.localizedDescription);
      } else {
        dispatch_async(dispatch_get_main_queue(), ^{
          // update UI
        });
      }
    }];
  } else {
    NSLog(@"Config not fetched");
    NSLog(@"Error %@", error.localizedDescription);
  }
}];
ObjCMigratedSnippets.m

چون این مقادیر پارامتر به‌روزشده بر رفتار و ظاهر برنامه‌تان تأثیر می‌گذارد، باید مقادیر واکشی‌شده را در زمانی فعال کنید که تجربه روانی برای کاربرتان تضمین شود، مثلاً دفعه بعدی که کاربر برنامه‌تان را باز می‌کند. برای اطلاعات بیشتر و مثال‌ها، به راهبردهای بار کردن «پیکربندی از راه دور» مراجعه کنید.

مرحله ۶: گوش دادن به به‌روزرسانی‌ها به‌صورت هم‌زمان

پس‌از واکشی مقادیر پارامتر، می‌توانید از Remote Config هم‌زمان برای گوش دادن به به‌روزرسانی‌های پس‌باند Remote Config استفاده کنید. وقتی به‌روزرسانی‌ها دردسترس باشند، Real-time Remote Config به دستگاه‌های متصل سیگنال می‌دهد و پس‌از انتشار نسخه جدید Remote Config، تغییرات را به‌طور خودکار واکشی می‌کند.

به‌روزرسانی‌های هم‌زمان توسط کیت توسعه نرم‌افزار Firebase برای پلاتفرم‌های Apple نسخه ۱۰.۷.۰ و بالاتر پشتیبانی می‌شود.

1. در برنامه‌تان، addOnConfigUpdateListener را فراخوانی کنید تا گوش دادن به به‌روزرسانی‌ها را شروع کنید و به‌طور خودکار مقادیر پارامتر جدید یا به‌روزشده را واکشی کنید. مثال زیر به‌روزرسانی‌ها را گوش می‌دهد و وقتی activateWithCompletionHandler فراخوانده می‌شود، از مقادیر جدید واکشی‌شده برای نمایش پیام خوشامدگویی به‌روزشده استفاده می‌کند.

   Swift

   remoteConfig.addOnConfigUpdateListener { configUpdate, error in
       guard let configUpdate, error == nil else {
         print("Error listening for config updates: \(error)")
       }
   
       print("Updated keys: \(configUpdate.updatedKeys)")
   
       self.remoteConfig.activate { changed, error in
         guard error == nil else { return self.displayError(error) }
         DispatchQueue.main.async {
           self.displayWelcome()
         }
       }
     }
     

   Objective-C

   __weak __typeof__(self) weakSelf = self;
     [self.remoteConfig addOnConfigUpdateListener:^(FIRRemoteConfigUpdate * _Nonnull configUpdate, NSError * _Nullable error) {
       if (error != nil) {
         NSLog(@"Error listening for config updates %@", error.localizedDescription);
       } else {
         NSLog(@"Updated keys: %@", configUpdate.updatedKeys);
   
         __typeof__(self) strongSelf = weakSelf;
         [strongSelf.remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
           if (error != nil) {
             NSLog(@"Activate error %@", error.localizedDescription);
           }
   
           dispatch_async(dispatch_get_main_queue(), ^{
             [strongSelf displayWelcome];
           });
         }];
       }
     }];
     

2. دفعه بعدی که نسخه جدیدی از Remote Config را منتشر می‌کنید، دستگاه‌هایی که برنامه شما را اجرا می‌کنند و منتظر تغییرات هستند، گرداننده تکمیل را فراخوانی خواهند کرد.

محدودسازی

اگر برنامه‌ای در مدت زمان کوتاهی بیش‌ازحد واکشی کند، تماس‌های واکشی محدود می‌شوند و کیت توسعه نرم‌افزار FIRRemoteConfigFetchStatusThrottled را برمی‌گرداند. قبل‌از نسخه ۶.۳.۰ کیت توسعه نرم‌افزار، حد مجاز ۵ درخواست واکشی در پنجره ۶۰ دقیقه‌ای بود (نسخه‌های جدیدتر حد مجاز آسان‌گیرانه‌تری دارند).

درطول توسعه برنامه، ممکن است بخواهید برای بازآوری حافظه نهان به‌طور مکرر (چندین بار در ساعت) واکشی کنید تا بتوانید به‌سرعت تکرار کنید و برنامه خود را توسعه دهید و آزمایش کنید. به‌روزرسانی‌های «پیکربندی از راه دور» هم‌زمان به‌طور خودکار حافظه نهان را هنگام به‌روزرسانی پیکربندی در سرور دور می‌زنند. برای تطبیق تکرار سریع در پروژه‌ای با توسعه‌دهندگان متعدد، می‌توانید موقتاً یک دارایی FIRRemoteConfigSettings با فاصله واکشی حداقل کم (MinimumFetchInterval) در برنامه‌تان اضافه کنید.

فاصله واکشی تولید پیش‌فرض و توصیه‌شده برای Remote Config ۱۲ ساعت است، یعنی پیکربندی‌ها بیشتر از یک‌بار در بازه ۱۲ ساعته از باطن واکشی نخواهند شد، صرف‌نظر از اینکه واقعاً چند تماس واکشی برقرار شده باشد. به‌طور خاص، حداقل فاصله واکشی به‌ترتیب زیر تعیین می‌شود:

1. پارامتر در fetch(long)
2. پارامتر در FIRRemoteConfigSettings.MinimumFetchInterval
3. مقدار پیش‌فرض ۱۲ ساعت