بدء استخدام ميزة "الإعداد عن بُعد" على أجهزة iOS

اختيار النظام الأساسي: iOS+ Android Web Flutter Unity C++


يمكنك استخدام Firebase Remote Config لتحديد المَعلمات في تطبيقك و تعديل قيمها في السحابة الإلكترونية، ما يتيح لك تغيير مظهر تطبيقك و سلوكه بدون توزيع تحديث للتطبيق. يرشدك هذا الدليل خلال خطوات البدء ويقدّم بعض نماذج الرموز البرمجية، وكلها متاحة لاستنساخها أو تنزيلها من مستودع firebase/quickstart-ios على GitHub.

الخطوة 1: إضافة Remote Config إلى تطبيقك

  1. إذا لم يسبق لك ذلك، أضِف Firebase إلى مشروعك على Apple project.

  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. في علامة التبويب "المَعلمات "، افتح القائمة وانقر على تنزيل القيم التلقائية.

    2. عندما يُطلب منك ذلك، فعِّل ملف 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 المنظَّمة

استخدام أغلفة الخصائص للإعدادات التصريحية في 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()
    }
  }
}

استخدِم غلاف الخاصية @RemoteConfigProperty عندما تريد طريقة تصريحية للوصول إلى قيم Remote Config في SwiftUI، مع دعم مضمّن للقيم التلقائية وإدارة مبسطة لعملية الإعداد.

الخطوة 4: ضبط قيم المَعلمات

باستخدام وحدة تحكّم Firebase أو واجهات برمجة التطبيقات الخلفية Remote Config ، يمكنك إنشاء قيم تلقائية جديدة في النظام الخلفي تلغي القيم داخل التطبيق وفقًا للمنطق الشرطي المطلوب أو استهداف المستخدمين. يرشدك هذا القسم خلال خطوات وحدة تحكّم Firebase لإنشاء هذه القيم.

  1. في وحدة تحكّم Firebase 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!")
    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 ConfigRemote Config تُرسِل ميزة "في الوقت الفعلي" Remote Config إشارات إلى الأجهزة المتصلة عندما تتوفّر تعديلات، و تسترجِع التغييرات تلقائيًا بعد نشر إصدار جديد من Remote Config.

تتوافق التعديلات في الوقت الفعلي مع الإصدار 10.7.0 من حزمة Firebase SDK للأنظمة الأساسية من 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، ستستخدِم الأجهزة التي تشغّل تطبيقك وتستمع إلى التغييرات معالج الإكمال.

التقييد

إذا استرجَع أحد التطبيقات البيانات عدة مرات خلال فترة زمنية قصيرة، يتم تقييد طلبات الاسترجاع وتعرض حزمة SDK الرمز FIRRemoteConfigFetchStatusThrottled. قبل الإصدار 6.3.0 من حزمة SDK، كان الحدّ الأقصى هو 5 طلبات استرجاع خلال فترة 60 دقيقة (تتضمّن الإصدارات الأحدث حدودًا أكثر تساهلاً).

أثناء تطوير التطبيق، قد تحتاج إلى الاسترجاع بشكل متكرر لتحديث ذاكرة التخزين المؤقت بشكل متكرر جدًا (عدة مرات في الساعة) ما يتيح لك التكرار السريع أثناء تطوير تطبيقك واختباره. تتجاوز تعديلات ميزة "الإعداد عن بُعد" في الوقت الفعلي ذاكرة التخزين المؤقت تلقائيًا عند تعديل الإعداد على الخادم. لاستيعاب التكرار السريع في مشروع يضم العديد من المطوّرين، يمكنك إضافة خاصية FIRRemoteConfigSettings مؤقتًا تتضمّن حدًا أدنى منخفضًا للفاصل الزمني بين عمليات الاسترجاع (MinimumFetchInterval) في تطبيقك.

الفاصل الزمني التلقائي والمقترَح للاسترجاع في مرحلة الإنتاج لـ Remote Config هو 12 ساعة، ما يعني أنّه لن يتم استرجاع الإعدادات من النظام الخلفي أكثر من مرة خلال فترة 12 ساعة، بغض النظر عن عدد طلبات الاسترجاع التي يتم إجراؤها فعليًا. على وجه التحديد، يتم تحديد الحد الأدنى للفاصل الزمني بين عمليات الاسترجاع بالترتيب التالي:

  1. المَعلمة في fetch(long)
  2. المَعلمة في FIRRemoteConfigSettings.MinimumFetchInterval
  3. القيمة التلقائية البالغة 12 ساعة