תחילת העבודה עם הגדרת תצורה מרחוק ב-Firebase


אפשר להשתמש ב-Firebase Remote Config כדי להגדיר פרמטרים באפליקציה ולעדכן את הערכים שלהם בענן, וכך לשנות את המראה וההתנהגות של האפליקציה בלי להפיץ עדכון לאפליקציה. במדריך הזה מוסבר איך מתחילים, ומופיע בו קוד לדוגמה. כל הקוד הזה זמין להעתקה (cloning) או להורדה מהמאגר firebase/quickstart-ios ב-GitHub.

שלב 1: מוסיפים את Remote Config לאפליקציה

  1. אם עדיין לא עשיתם זאת, מוסיפים את Firebase לפרויקט ב-Apple.

  2. ב-Remote Config, Google Analytics נדרש לטירגוט המותנה של מופעי האפליקציה למאפייני משתמשים ולקהלים. חשוב לוודא שמפעילים את Google Analytics בפרויקט.

  3. יוצרים את האובייקט היחיד Remote Config, כפי שמתואר בדוגמה הבאה:

    Swift

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

    Objective-C

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

האובייקט הזה משמש לאחסון ערכי ברירת המחדל של הפרמטרים באפליקציה, לאחזור ערכי פרמטרים מעודכנים מהקצה העורפי של Remote Config ולשליטה במועד שבו הערכים שאוחזרו יהיו זמינים לאפליקציה.

במהלך הפיתוח, מומלץ להגדיר מרווח אחזור מינימלי נמוך יחסית. מידע נוסף זמין במאמר צמצום קצב העברת הנתונים.

שלב 2: מגדירים ערכי ברירת מחדל של פרמטרים באפליקציה

אפשר להגדיר ערכי ברירת מחדל של פרמטרים באפליקציה באובייקט 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

    Firebase מסוף

    1. בכרטיסייה Parameters, פותחים את Menu ובוחרים באפשרות Download default values.

    2. כשמוצגת בקשה, מפעילים את האפשרות ‎.plist for iOS ולוחצים על Download file.

  2. מוסיפים את הערכים האלה לאובייקט Remote Config באמצעות setDefaults:. בדוגמה הבאה מגדירים ערכי ברירת מחדל באפליקציה מקובץ plist:

    Swift

    remoteConfig.setDefaults(fromPlist: "RemoteConfigDefaults")
    ViewController.swift

    Objective-C

    [self.remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];
    ViewController.m

שלב 3: מקבלים ערכי פרמטר לשימוש באפליקציה

עכשיו אפשר לקבל ערכי פרמטרים מהאובייקט 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

Wrappers של נכסים הם תכונה חזקה של Swift שמאפשרת להוסיף התנהגות מותאמת אישית להצהרות על נכסים. ב-SwiftUI, נעשה שימוש ב-wrappers של נכסים כדי לנהל את המצב, קישורים והתנהגויות אחרות של נכסים. מידע נוסף זמין במדריך השפה 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()
    }
  }
}

משתמשים ב-@RemoteConfigProperty property wrapper כשרוצים דרך אופרטיבית לגשת לערכים של Remote Config ב-SwiftUI, עם תמיכה מובנית בערכים שמוגדרים כברירת מחדל וניהול פשוט יותר של ההגדרות.

שלב 4: מגדירים את ערכי הפרמטרים

באמצעות מסוף Firebase או ממשקי ה-API לקצה העורפי של Remote Config, אפשר ליצור ערכי ברירת מחדל חדשים לקצה העורפי שיבטלו את הערכים באפליקציה בהתאם ללוגיקת התנאי או לטירגוט המשתמשים הרצויים. בקטע הזה מוסבר איך יוצרים את הערכים האלה במסוף Firebase.

  1. פותחים את הפרויקט במסוף Firebase.
  2. בתפריט, בוחרים באפשרות Remote Config כדי להציג את לוח הבקרה Remote Config.
  3. מגדירים פרמטרים עם אותם שמות כמו הפרמטרים שהוגדרו באפליקציה. לכל פרמטר אפשר להגדיר ערך ברירת מחדל (שיחליף בסופו של דבר את ערך ברירת המחדל באפליקציה), ואפשר גם להגדיר ערכים מותנים. למידע נוסף, ראו פרמטרים ותנאים של Remote Config.

  4. אם משתמשים בתנאי אות בהתאמה אישית, צריך להגדיר את המאפיינים ואת הערכים שלהם. בדוגמאות הבאות מוסבר איך מגדירים תנאי אות בהתאמה אישית.

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

שלב 5: אחזור והפעלה של ערכים

כדי לאחזר ערכים של פרמטרים מ-Remote Config, צריך להפעיל את השיטה fetchWithCompletionHandler: או את השיטה fetchWithExpirationDuration:completionHandler:. כל הערכים שהגדרתם בקצה העורפי מאוחזרים ומאוחסנים במטמון באובייקט Remote Config.

במקרים שבהם רוצים לאחזר ולהפעיל ערכים בקריאה אחת, משתמשים ב-fetchAndActivateWithCompletionHandler:.

בדוגמה הזו, האפליקציה מאחזרת ערכים מקצה העורפי של Remote Config (לא ערכים שנשמרו במטמון) ומפעילה את activateWithCompletionHandler: כדי להפוך אותם לזמינים לאפליקציה:

Swift

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

Objective-C

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

מאחר שערכים מעודכנים של פרמטרים משפיעים על ההתנהגות והמראה של האפליקציה, כדאי להפעיל את הערכים שאוחזרו בזמן שמבטיח חוויה חלקה למשתמש, למשל בפעם הבאה שהמשתמש יפתח את האפליקציה. למידע נוסף ולדוגמאות, אפשר לעיין במאמר אסטרטגיות טעינה של Remote Config.

שלב 6: האזנה לעדכונים בזמן אמת

אחרי שאתם מאחזרים את ערכי הפרמטרים, אתם יכולים להשתמש ב-Remote Config בזמן אמת כדי להאזין לעדכונים מהקצה העורפי של Remote Config. Remote Config מאותת למכשירים מחוברים בזמן אמת כשיש עדכונים זמינים, ומאחזר את השינויים באופן אוטומטי אחרי שמפרסמים גרסה חדשה של Remote Config.

עדכונים בזמן אמת נתמכים ב-Firebase SDK לפלטפורמות Apple בגרסה 10.7.0 ואילך.

  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, במכשירים שבהם האפליקציה פועלת ומאזינים לשינויים יתבצע קריאה למטפל ההשלמה.

ויסות נתונים (throttle)

אם אפליקציה מבצעת אחזור פעמים רבות מדי בפרק זמן קצר, המערכת תגביל את הקריאות לאחזור וה-SDK יחזיר את הערך FIRRemoteConfigFetchStatusThrottled. לפני גרסת ה-SDK 6.3.0, המגבלה הייתה 5 בקשות אחזור בחלון של 60 דקות (בגרסאות חדשות יותר יש מגבלות פחות מחמירות).

במהלך פיתוח האפליקציה, מומלץ לבצע אחזור בתדירות גבוהה כדי לרענן את המטמון לעיתים קרובות (פעמים רבות בשעה), כדי לאפשר לכם לבצע איטרציות במהירות במהלך הפיתוח והבדיקה של האפליקציה. עדכונים של Remote Config בזמן אמת עוקפים את המטמון באופן אוטומטי כשהתצורה מתעדכנת בשרת. כדי לבצע שינויים מהירים בפרויקט עם מפתחים רבים, אפשר להוסיף לאפליקציה באופן זמני את הנכס FIRRemoteConfigSettings עם מרווח אחזור מינימלי נמוך (MinimumFetchInterval).

מרווח האחזור שמוגדר כברירת מחדל ומומלץ בסביבת הייצור של Remote Config הוא 12 שעות. כלומר, לא תתבצע אחזור של הגדרות הקצה העורפי יותר מפעם אחת בחלון של 12 שעות, ללא קשר למספר הקריאות לאחזור שבוצעו בפועל. באופן ספציפי, מרווח האחזור המינימלי נקבע לפי הסדר הבא:

  1. הפרמטר ב-fetch(long)
  2. הפרמטר ב-FIRRemoteConfigSettings.MinimumFetchInterval
  3. ערך ברירת המחדל של 12 שעות

השלבים הבאים

אם עדיין לא עשיתם זאת, כדאי לעיין בRemote Config תרחישים לדוגמה ולקרוא את המסמכים בנושא מושגים מרכזיים ואסטרטגיות מתקדמות, כולל: