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

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

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

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

שלב 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
   

   כדי ליצור טוקן למוכ"ז, מריצים את הפקודה הבאה באמצעות Google Cloud CLI או Cloud Shell:

   gcloud auth print-access-token
   

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

   מסוף Firebase

   1. במסוף Firebase, נכנסים לדף DevOps & Engagement (DevOps ומעורבות) > Remote Config (הגדרת תצורה מרחוק) > Parameters (פרמטרים).

   2. פותחים את more_vert התפריט ובוחרים באפשרות הורדת ערכי ברירת המחדל.

   3. כשמוצגת בקשה, מפעילים את ‎.plist ל-iOS ולוחצים על הורדת הקובץ.

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

   Swift

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

   Objective-C

   [remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];
   ObjCMigratedSnippets.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

עטיפות של מאפיינים הן תכונה יעילה של 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()
    }
  }
}

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

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

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

1. במסוף Firebase, נכנסים לדף DevOps & Engagement (DevOps ומעורבות) > Remote Config (הגדרת תצורה מרחוק) > Parameters (פרמטרים).

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

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

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

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

בדוגמה הזו, המערכת מאחזרת ערכים מה-backend של 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

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

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

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

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

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

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

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

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

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