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

انتخاب پلاتفرم: iOS+ Android Web Flutter Unity C++‎


می‌توانید از 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

    Objective-C

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

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

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

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

می‌توانید مقادیر پارامتر پیش‌فرض درون‌برنامه‌ای را در Remote Config object تنظیم کنید تا برنامه‌تان قبل‌از اتصال به زیرینه 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. منو را باز کنید و بارگیری مقادیر پیش‌فرض را انتخاب کنید.

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

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

    Swift

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

    Objective-C

    [remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];

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

اکنون می‌توانید مقادیر پارامتر را از شیء 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 ارائه دهید.

استفاده از «پوشش‌های دارایی» برای پیکربندی بیانیه در 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: را فرا می‌خواند تا آن‌ها را برای برنامه دردسترس قرار دهد:

Swift

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.")")
  }
}

Objective-C

[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);
  }
}];

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

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

پس‌از واکشی مقادیر پارامتر، می‌توانید از Remote Config هم‌زمان برای شنیدن به‌روزرسانی‌های Remote Config زیرینه استفاده کنید. وقتی به‌روزرسانی دردسترس باشد، 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. مقدار پیش‌فرض ۱۲ ساعت