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

בחירת פלטפורמה:

iOS+‎ Android אינטרנט Flutter Unity C++‎

אתם יכולים להשתמש ב-Firebase Remote Config כדי להגדיר פרמטרים באפליקציה ולעדכן את הערכים שלהם בענן, וכך לשנות את המראה וההתנהגות של האפליקציה בלי להפיץ עדכון לאפליקציה. במדריך הזה מוסבר איך להתחיל לעבוד עם Firebase, ומוצג בו קוד לדוגמה שאפשר לשכפל או להוריד ממאגר 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, וכדי שערכי ברירת המחדל יהיו זמינים אם לא הוגדרו ערכים בקצה העורפי.

חשוב: אל תאחסנו מידע סודי במפתחות או בערכים של הפרמטר 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 & Engagement ‏> הגדרת תצורה מרחוק ‏> Parameters.

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

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

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

   Swift

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

   Objective-C

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

הערה: קטעי הקוד האלה מתייחסים לקובץ RemoteConfigDefaults.plist מהפרויקט לדוגמה quickstart-ios. אם משתמשים בקובץ ברירות המחדל שהורדתם, משתמשים ב-remote_config_defaults.

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

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

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);
  }
}];
ObjCMigratedSnippets.m

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

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

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

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

חשוב: כדי להשתמש ב-Remote Config בזמן אמת, צריך גם את Firebase Remote Config Realtime API, שכבר אמור להיות מופעל. כדי לוודא שהם מופעלים, פותחים את מסוף Google Cloud, בוחרים את הפרויקט ופותחים את הדף APIs and Services. ה-API אמור להופיע כ"מופעל". אם הוא לא מופיע או לא מופעל, לוחצים על Enable APIs & Services, מחפשים את Firebase Remote Config Realtime API ומפעילים אותו.

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 דקות (בגרסאות חדשות יותר המגבלות פחות מחמירות).

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

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

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

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

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