· 6 years ago · Oct 11, 2019, 01:20 PM
1/*
2 * Copyright 2019 Google
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#import <Foundation/Foundation.h>
18
19@class FIRApp;
20
21/// The Firebase Remote Config service default namespace, to be used if the API method does not
22/// specify a different namespace. Use the default namespace if configuring from the Google Firebase
23/// service.
24extern NSString *const _Nonnull FIRNamespaceGoogleMobilePlatform NS_SWIFT_NAME(
25 NamespaceGoogleMobilePlatform);
26
27/// Key used to manage throttling in NSError user info when the refreshing of Remote Config
28/// parameter values (data) is throttled. The value of this key is the elapsed time since 1970,
29/// measured in seconds.
30extern NSString *const _Nonnull FIRRemoteConfigThrottledEndTimeInSecondsKey NS_SWIFT_NAME(
31 RemoteConfigThrottledEndTimeInSecondsKey);
32
33/// Indicates whether updated data was successfully fetched.
34typedef NS_ENUM(NSInteger, FIRRemoteConfigFetchStatus) {
35 /// Config has never been fetched.
36 FIRRemoteConfigFetchStatusNoFetchYet,
37 /// Config fetch succeeded.
38 FIRRemoteConfigFetchStatusSuccess,
39 /// Config fetch failed.
40 FIRRemoteConfigFetchStatusFailure,
41 /// Config fetch was throttled.
42 FIRRemoteConfigFetchStatusThrottled,
43} NS_SWIFT_NAME(RemoteConfigFetchStatus);
44
45/// Indicates whether updated data was successfully fetched and activated.
46typedef NS_ENUM(NSInteger, FIRRemoteConfigFetchAndActivateStatus) {
47 /// The remote fetch succeeded and fetched data was activated.
48 FIRRemoteConfigFetchAndActivateStatusSuccessFetchedFromRemote,
49 /// The fetch and activate succeeded from already fetched but yet unexpired config data. You can
50 /// control this using minimumFetchInterval property in FIRRemoteConfigSettings.
51 FIRRemoteConfigFetchAndActivateStatusSuccessUsingPreFetchedData,
52 /// The fetch and activate failed.
53 FIRRemoteConfigFetchAndActivateStatusError
54} NS_SWIFT_NAME(RemoteConfigFetchAndActivateStatus);
55
56/// Remote Config error domain that handles errors when fetching data from the service.
57extern NSString *const _Nonnull FIRRemoteConfigErrorDomain NS_SWIFT_NAME(RemoteConfigErrorDomain);
58/// Firebase Remote Config service fetch error.
59typedef NS_ENUM(NSInteger, FIRRemoteConfigError) {
60 /// Unknown or no error.
61 FIRRemoteConfigErrorUnknown = 8001,
62 /// Frequency of fetch requests exceeds throttled limit.
63 FIRRemoteConfigErrorThrottled = 8002,
64 /// Internal error that covers all internal HTTP errors.
65 FIRRemoteConfigErrorInternalError = 8003,
66} NS_SWIFT_NAME(RemoteConfigError);
67
68/// Enumerated value that indicates the source of Remote Config data. Data can come from
69/// the Remote Config service, the DefaultConfig that is available when the app is first installed,
70/// or a static initialized value if data is not available from the service or DefaultConfig.
71typedef NS_ENUM(NSInteger, FIRRemoteConfigSource) {
72 FIRRemoteConfigSourceRemote, ///< The data source is the Remote Config service.
73 FIRRemoteConfigSourceDefault, ///< The data source is the DefaultConfig defined for this app.
74 FIRRemoteConfigSourceStatic, ///< The data doesn't exist, return a static initialized value.
75} NS_SWIFT_NAME(RemoteConfigSource);
76
77/// Completion handler invoked by fetch methods when they get a response from the server.
78///
79/// @param status Config fetching status.
80/// @param error Error message on failure.
81typedef void (^FIRRemoteConfigFetchCompletion)(FIRRemoteConfigFetchStatus status,
82 NSError *_Nullable error)
83 NS_SWIFT_NAME(RemoteConfigFetchCompletion);
84
85/// Completion handler invoked by activate method upon completion.
86/// @param error Error message on failure. Nil if activation was successful.
87typedef void (^FIRRemoteConfigActivateCompletion)(NSError *_Nullable error)
88 NS_SWIFT_NAME(RemoteConfigActivateCompletion);
89
90/// Completion handler invoked upon completion of Remote Config initialization.
91///
92/// @param initializationError nil if initialization succeeded.
93typedef void (^FIRRemoteConfigInitializationCompletion)(NSError *_Nullable initializationError)
94 NS_SWIFT_NAME(RemoteConfigInitializationCompletion);
95
96/// Completion handler invoked by the fetchAndActivate method. Used to convey status of fetch and,
97/// if successful, resultant activate call
98/// @param status Config fetching status.
99/// @param error Error message on failure of config fetch
100typedef void (^FIRRemoteConfigFetchAndActivateCompletion)(
101 FIRRemoteConfigFetchAndActivateStatus status, NSError *_Nullable error)
102 NS_SWIFT_NAME(RemoteConfigFetchAndActivateCompletion);
103
104#pragma mark - FIRRemoteConfigValue
105/// This class provides a wrapper for Remote Config parameter values, with methods to get parameter
106/// values as different data types.
107NS_SWIFT_NAME(RemoteConfigValue)
108@interface FIRRemoteConfigValue : NSObject <NSCopying>
109/// Gets the value as a string.
110@property(nonatomic, readonly, nullable) NSString *stringValue;
111/// Gets the value as a number value.
112@property(nonatomic, readonly, nullable) NSNumber *numberValue;
113/// Gets the value as a NSData object.
114@property(nonatomic, readonly, nonnull) NSData *dataValue;
115/// Gets the value as a boolean.
116@property(nonatomic, readonly) BOOL boolValue;
117/// Gets a foundation object (NSDictionary / NSArray) by parsing the value as JSON. This method uses
118/// NSJSONSerialization's JSONObjectWithData method with an options value of 0.
119@property(nonatomic, readonly, nullable) id JSONValue NS_SWIFT_NAME(jsonValue);
120/// Identifies the source of the fetched value.
121@property(nonatomic, readonly) FIRRemoteConfigSource source;
122@end
123
124#pragma mark - FIRRemoteConfigSettings
125/// Firebase Remote Config settings.
126NS_SWIFT_NAME(RemoteConfigSettings)
127@interface FIRRemoteConfigSettings : NSObject
128/// Indicates the default value in seconds to set for the minimum interval that needs to elapse
129/// before a fetch request can again be made to the Remote Config backend. After a fetch request to
130/// the backend has succeeded, no additional fetch requests to the backend will be allowed until the
131/// minimum fetch interval expires. Note that you can override this default on a per-fetch request
132/// basis using -[FIRRemoteConfig fetchWithExpirationDuration:completionHandler]. For E.g. setting
133/// the expiration duration to 0 in the fetch request will override the minimumFetchInterval and
134/// allow the request to the backend.
135@property(nonatomic, assign) NSTimeInterval minimumFetchInterval;
136/// Indicates the default value in seconds to abandon a pending fetch request made to the backend.
137/// This value is set for outgoing requests as the timeoutIntervalForRequest as well as the
138/// timeoutIntervalForResource on the NSURLSession's configuration.
139@property(nonatomic, assign) NSTimeInterval fetchTimeout;
140/// Indicates whether Developer Mode is enabled.
141@property(nonatomic, readonly) BOOL isDeveloperModeEnabled DEPRECATED_MSG_ATTRIBUTE(
142 "This no longer needs to be set during development. Refer to documentation for additional "
143 "details.");
144/// Initializes FIRRemoteConfigSettings, which is used to set properties for custom settings. To
145/// make custom settings take effect, pass the FIRRemoteConfigSettings instance to the
146/// configSettings property of FIRRemoteConfig.
147- (nonnull FIRRemoteConfigSettings *)initWithDeveloperModeEnabled:(BOOL)developerModeEnabled
148 DEPRECATED_MSG_ATTRIBUTE("This no longer needs to be set during development. Refer to "
149 "documentation for additional details.");
150@end
151
152#pragma mark - FIRRemoteConfig
153/// Firebase Remote Config class. The shared instance method +remoteConfig can be created and used
154/// to fetch, activate and read config results and set default config results.
155NS_SWIFT_NAME(RemoteConfig)
156@interface FIRRemoteConfig : NSObject <NSFastEnumeration>
157/// Last successful fetch completion time.
158@property(nonatomic, readwrite, strong, nullable) NSDate *lastFetchTime;
159/// Last fetch status. The status can be any enumerated value from FIRRemoteConfigFetchStatus.
160@property(nonatomic, readonly, assign) FIRRemoteConfigFetchStatus lastFetchStatus;
161/// Config settings are custom settings.
162@property(nonatomic, readwrite, strong, nonnull) FIRRemoteConfigSettings *configSettings;
163
164/// Returns the FIRRemoteConfig instance configured for the default Firebase app. This singleton
165/// object contains the complete set of Remote Config parameter values available to the app,
166/// including the Active Config and Default Config. This object also caches values fetched from the
167/// Remote Config Server until they are copied to the Active Config by calling activateFetched. When
168/// you fetch values from the Remote Config Server using the default Firebase namespace service, you
169/// should use this class method to create a shared instance of the FIRRemoteConfig object to ensure
170/// that your app will function properly with the Remote Config Server and the Firebase service.
171+ (nonnull FIRRemoteConfig *)remoteConfig NS_SWIFT_NAME(remoteConfig());
172
173/// Returns the FIRRemoteConfig instance for your (non-default) Firebase appID. Note that Firebase
174/// analytics does not work for non-default app instances. This singleton object contains the
175/// complete set of Remote Config parameter values available to the app, including the Active Config
176/// and Default Config. This object also caches values fetched from the Remote Config Server until
177/// they are copied to the Active Config by calling activateFetched. When you fetch values from the
178/// Remote Config Server using the default Firebase namespace service, you should use this class
179/// method to create a shared instance of the FIRRemoteConfig object to ensure that your app will
180/// function properly with the Remote Config Server and the Firebase service.
181+ (nonnull FIRRemoteConfig *)remoteConfigWithApp:(nonnull FIRApp *)app
182 NS_SWIFT_NAME(remoteConfig(app:));
183
184/// Unavailable. Use +remoteConfig instead.
185- (nonnull instancetype)init __attribute__((unavailable("Use +remoteConfig instead.")));
186
187/// Ensures initialization is complete and clients can begin querying for Remote Config values.
188/// @param completionHandler Initialization complete callback.
189- (void)ensureInitializedWithCompletionHandler:
190 (nonnull FIRRemoteConfigInitializationCompletion)completionHandler;
191#pragma mark - Fetch
192/// Fetches Remote Config data with a callback. Call activateFetched to make fetched data available
193/// to your app.
194///
195/// Note: This method uses a Firebase Instance ID token to identify the app instance, and once it's
196/// called, it periodically sends data to the Firebase backend. (see
197/// `[FIRInstanceID getIDWithHandler:]`).
198/// To stop the periodic sync, developers need to call `[FIRInstanceID deleteIDWithHandler:]` and
199/// avoid calling this method again.
200///
201/// @param completionHandler Fetch operation callback.
202- (void)fetchWithCompletionHandler:(nullable FIRRemoteConfigFetchCompletion)completionHandler;
203
204/// Fetches Remote Config data and sets a duration that specifies how long config data lasts.
205/// Call activateFetched to make fetched data available to your app.
206///
207/// Note: This method uses a Firebase Instance ID token to identify the app instance, and once it's
208/// called, it periodically sends data to the Firebase backend. (see
209/// `[FIRInstanceID getIDWithHandler:]`).
210/// To stop the periodic sync, developers need to call `[FIRInstanceID deleteIDWithHandler:]` and
211/// avoid calling this method again.
212///
213/// @param expirationDuration Override the (default or optionally set minimumFetchInterval property
214/// in FIRRemoteConfigSettings) minimumFetchInterval for only the current request, in seconds.
215/// Setting a value of 0 seconds will force a fetch to the backend.
216/// @param completionHandler Fetch operation callback.
217- (void)fetchWithExpirationDuration:(NSTimeInterval)expirationDuration
218 completionHandler:(nullable FIRRemoteConfigFetchCompletion)completionHandler;
219
220/// Fetches Remote Config data and if successful, activates fetched data. Optional completion
221/// handler callback is invoked after the attempted activation of data, if the fetch call succeeded.
222///
223/// Note: This method uses a Firebase Instance ID token to identify the app instance, and once it's
224/// called, it periodically sends data to the Firebase backend. (see
225/// `[FIRInstanceID getIDWithHandler:]`).
226/// To stop the periodic sync, developers need to call `[FIRInstanceID deleteIDWithHandler:]` and
227/// avoid calling this method again.
228///
229/// @param completionHandler Fetch operation callback.
230- (void)fetchAndActivateWithCompletionHandler:
231 (nullable FIRRemoteConfigFetchAndActivateCompletion)completionHandler;
232
233#pragma mark - Apply
234
235/// Applies Fetched Config data to the Active Config, causing updates to the behavior and appearance
236/// of the app to take effect (depending on how config data is used in the app).
237/// @param completionHandler Activate operation callback.
238- (void)activateWithCompletionHandler:(nullable FIRRemoteConfigActivateCompletion)completionHandler;
239
240/// This method is deprecated. Please use -[FIRRemoteConfig activateWithCompletionHandler:] instead.
241/// Applies Fetched Config data to the Active Config, causing updates to the behavior and appearance
242/// of the app to take effect (depending on how config data is used in the app).
243/// Returns true if there was a Fetched Config, and it was activated.
244/// Returns false if no Fetched Config was found, or the Fetched Config was already activated.
245- (BOOL)activateFetched DEPRECATED_MSG_ATTRIBUTE("Use -[FIRRemoteConfig activate] "
246 "instead.");
247
248#pragma mark - Get Config
249/// Enables access to configuration values by using object subscripting syntax.
250/// <pre>
251/// // Example:
252/// FIRRemoteConfig *config = [FIRRemoteConfig remoteConfig];
253/// FIRRemoteConfigValue *value = config[@"yourKey"];
254/// BOOL b = value.boolValue;
255/// NSNumber *number = config[@"yourKey"].numberValue;
256/// </pre>
257- (nonnull FIRRemoteConfigValue *)objectForKeyedSubscript:(nonnull NSString *)key;
258
259/// Gets the config value.
260/// @param key Config key.
261- (nonnull FIRRemoteConfigValue *)configValueForKey:(nullable NSString *)key;
262
263/// Gets the config value of a given namespace.
264/// @param key Config key.
265/// @param aNamespace Config results under a given namespace.
266- (nonnull FIRRemoteConfigValue *)configValueForKey:(nullable NSString *)key
267 namespace:(nullable NSString *)aNamespace
268 DEPRECATED_MSG_ATTRIBUTE("Use -[FIRRemoteConfig configValueForKey:] "
269 "instead.");
270
271/// Gets the config value of a given namespace and a given source.
272/// @param key Config key.
273/// @param source Config value source.
274- (nonnull FIRRemoteConfigValue *)configValueForKey:(nullable NSString *)key
275 source:(FIRRemoteConfigSource)source;
276
277/// Gets the config value of a given namespace and a given source.
278/// @param key Config key.
279/// @param aNamespace Config results under a given namespace.
280/// @param source Config value source.
281- (nonnull FIRRemoteConfigValue *)configValueForKey:(nullable NSString *)key
282 namespace:(nullable NSString *)aNamespace
283 source:(FIRRemoteConfigSource)source
284 DEPRECATED_MSG_ATTRIBUTE("Use -[FIRRemoteConfig configValueForKey:source:] "
285 "instead.");
286
287/// Gets all the parameter keys from a given source and a given namespace.
288///
289/// @param source The config data source.
290/// @return An array of keys under the given source and namespace.
291- (nonnull NSArray<NSString *> *)allKeysFromSource:(FIRRemoteConfigSource)source;
292
293/// Gets all the parameter keys from a given source and a given namespace.
294///
295/// @param source The config data source.
296/// @param aNamespace The config data namespace.
297/// @return An array of keys under the given source and namespace.
298- (nonnull NSArray<NSString *> *)allKeysFromSource:(FIRRemoteConfigSource)source
299 namespace:(nullable NSString *)aNamespace
300 DEPRECATED_MSG_ATTRIBUTE("Use -[FIRRemoteConfig allKeysFromSource:] instead.");
301
302/// Returns the set of parameter keys that start with the given prefix, from the default namespace
303/// in the active config.
304///
305/// @param prefix The key prefix to look for. If prefix is nil or empty, returns all the
306/// keys.
307/// @return The set of parameter keys that start with the specified prefix.
308- (nonnull NSSet<NSString *> *)keysWithPrefix:(nullable NSString *)prefix;
309
310/// Returns the set of parameter keys that start with the given prefix, from the given namespace in
311/// the active config.
312///
313/// @param prefix The key prefix to look for. If prefix is nil or empty, returns all the
314/// keys in the given namespace.
315/// @param aNamespace The namespace in which to look up the keys. If the namespace is invalid,
316/// returns an empty set.
317/// @return The set of parameter keys that start with the specified prefix.
318- (nonnull NSSet<NSString *> *)keysWithPrefix:(nullable NSString *)prefix
319 namespace:(nullable NSString *)aNamespace
320 DEPRECATED_MSG_ATTRIBUTE("Use -[FIRRemoteConfig keysWithPrefix:] instead.");
321
322#pragma mark - Defaults
323/// Sets config defaults for parameter keys and values in the default namespace config.
324/// @param defaults A dictionary mapping a NSString * key to a NSObject * value.
325- (void)setDefaults:(nullable NSDictionary<NSString *, NSObject *> *)defaults;
326
327/// Sets config defaults for parameter keys and values in the default namespace config.
328///
329/// @param defaults A dictionary mapping a NSString * key to a NSObject * value.
330/// @param aNamespace Config under a given namespace.
331- (void)setDefaults:(nullable NSDictionary<NSString *, NSObject *> *)defaults
332 namespace:(nullable NSString *)aNamespace
333 DEPRECATED_MSG_ATTRIBUTE("Use -[FIRRemoteConfig setDefaults:] instead.");
334
335/// Sets default configs from plist for default namespace;
336/// @param fileName The plist file name, with no file name extension. For example, if the plist file
337/// is defaultSamples.plist, call:
338/// [[FIRRemoteConfig remoteConfig] setDefaultsFromPlistFileName:@"defaultSamples"];
339- (void)setDefaultsFromPlistFileName:(nullable NSString *)fileName
340 NS_SWIFT_NAME(setDefaults(fromPlist:));
341
342/// Sets default configs from plist for a given namespace;
343/// @param fileName The plist file name, with no file name extension. For example, if the plist file
344/// is defaultSamples.plist, call:
345/// [[FIRRemoteConfig remoteConfig] setDefaultsFromPlistFileName:@"defaultSamples"];
346/// @param aNamespace The namespace where the default config is set.
347- (void)setDefaultsFromPlistFileName:(nullable NSString *)fileName
348 namespace:(nullable NSString *)aNamespace
349 NS_SWIFT_NAME(setDefaults(fromPlist:namespace:))
350 DEPRECATED_MSG_ATTRIBUTE("Use -[FIRRemoteConfig setDefaultsFromPlistFileName:] instead.");
351
352/// Returns the default value of a given key and a given namespace from the default config.
353///
354/// @param key The parameter key of default config.
355/// @return Returns the default value of the specified key and namespace. Returns
356/// nil if the key or namespace doesn't exist in the default config.
357- (nullable FIRRemoteConfigValue *)defaultValueForKey:(nullable NSString *)key;
358
359/// Returns the default value of a given key and a given namespace from the default config.
360///
361/// @param key The parameter key of default config.
362/// @param aNamespace The namespace of default config.
363/// @return Returns the default value of the specified key and namespace. Returns
364/// nil if the key or namespace doesn't exist in the default config.
365- (nullable FIRRemoteConfigValue *)defaultValueForKey:(nullable NSString *)key
366 namespace:(nullable NSString *)aNamespace
367 DEPRECATED_MSG_ATTRIBUTE("Use -[FIRRemoteConfig defaultValueForKey:] instead.");
368
369@end