Functions

Availability: iOS apps only.

You must call APLApplicationDidFinishLaunchingWithOptions in your app delegate’s application:didFinishLaunchingWithOptions: method.

Objective-C example

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  APLApplicationDidFinishLaunchingWithOptions(launchOptions);
  return YES;
}

Swift example

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  APLApplicationDidFinishLaunchingWithOptions(launchOptions)
  return true
}

Availability: iOS apps only.

You must call APLApplicationOpenURL in your app delegate’s application:openURL:options: method.

Objective-C example

- (BOOL) application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
  return APLApplicationOpenURL(url);
}

Swift example

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
  return APLApplicationOpenURL(url)
}

Availability: watchOS extensions only.

You must call APLApplicationDidFinishLaunching in your extension’s delegate applicationDidFinishLaunching method.

Objective-C example

- (void) applicationDidFinishLaunching {
    APLApplicationDidFinishLaunching();
}

Swift example

func applicationDidFinishLaunching() {
  APLApplicationDidFinishLaunching()
}

Availability: watchOS extensions only.

Receives configuration commands and payloads from the paired iPhone’s Appfigurate app.

If your watch app has its own WCSessionDelegate, then call the APLSessionDidReceiveMessage() function from within your session:didReceiveMessage:replyHandler: method (see examples below). If your watch app does not have its own WCSessionDelegate then you do not need to do anything - Appfigurate library installs a WCSessionDelegate and calls APLSessionDidReceiveMessage() automatically.

Objective-C example

- (void) session: (WCSession*) session didReceiveMessage: (NSDictionary<NSString*,id>*) message
   replyHandler: (void (^)(NSDictionary<NSString*,id>*)) replyHandler {
   NSDictionary* reply = APLSessionDidReceiveMessage(message);
   if (reply != nil)
       replyHandler(reply);
   else
      ...

Swift example

func session(_ session: WCSession, didReceiveMessage message: [String : Any], replyHandler: @escaping ([String : Any]) -> Void) {
  let reply = APLSessionDidReceiveMessage(message)
  if reply != nil {
    replyHandler(reply)
  } else {
    ...

Availability: All.

Returns the version of the Appfigurate library in the format “major.minor.patch”. e.g. “5.1.2”

Availability: All.

Registers a delegate method that will be called back when Appfigurate has updated the configuration of the app or extension. See also APLAddConfigurationUpdatedBlock function for block based callback.

Availability: All.

Registers a block that will be called back when Appfigurate has updated the configuration of the app or extension. Returns an opaque object to act as the observer. See also APLRemoveConfigurationUpdatedBlock.

Availability: All.

Unregisters the delegate method that will be called back when Appfigurate has updated the configuration of the application. You may optionally call this method before the target is deallocated.

Availability: All.

Unregisters the block that will be called back when Appfigurate has updated the configuration of the application. You must call this method before the block is deallocated. The observer argument is the result of APLAddConfigurationUpdatedBlock.

Availability: All.

Saves the configuration persisted in the keychain into temporary storage. Some apps have functionality to erase the keychain to reset apps back to “factory defaults”, which has the side effect of removing any Appfigurate configuration persisted in the keychain. Usage example:

Objective-C example

- (void) eraseKeychain {
   APLSaveConfiguration();
   NSArray* secItemClasses = @[(__bridge id) kSecClassGenericPassword,
     (__bridge id) kSecClassInternetPassword,
     (__bridge id) kSecClassCertificate,
     (__bridge id) kSecClassKey,
     (__bridge id) kSecClassIdentity];
   for (id secItemClass in secItemClasses) {
     NSDictionary *spec = @{(__bridge id)kSecClass: secItemClass};
     SecItemDelete((__bridge CFDictionaryRef)spec);
   }
   APLRestoreConfiguration();
}

Availability: All.

Restores the configuration from temporary storage back into the keychain. See also APLSaveConfiguration for more details and usage example.

Availability: All.

The application or framework that links the static AppfigurateLibrary.xcframework must define a function with the following prototype that returns the Class (Objective-C) or AnyClass (Swift) of your APLConfiguration subclass.

Objective-C example

- (Class) _Nonnull APLConfigurationClass(void) {
  return [ExampleConfiguration class];
}

Swift example

@_cdecl("APLConfigurationClass")
func APLConfigurationClass() -> AnyClass {
    return ExampleConfiguration.self
}

Availability: iOS XCUITest automation testing only.

Sends a message to the application under test, and waits for a response. You can only call this function from within an XCUITest automation test case. name is the message name, must not be nil or blank, maximum 255 bytes after encoding with UTF-8. plist is a property list object or nil. timeout is the duration in seconds you expect to receive a response, otherwise an AppfigurateLibraryException is thrown (minimum of 3.0 seconds). Returns a property list object or nil from the application under test. See also APLAutomationMessageReceivedBlock.

Objective-C example

- (void) testLogin {
  XCUIApplication *app = [XCUIApplication new];
  [app launch];

  APLAutomationSendMessage(@"SetResponseData", @{
    @"Request": @"/login",
    @"Status": [NSNumber numberWithInt: 200],
    @"Response": @"{'Customer':'2311569'}"
  }, 3.0);
  ...

Swift example

func testLogin() {
  var app = XCUIApplication()
  app.launch

  APLAutomationSendMessage("SetResponseData", [
    "Request": "/login",
    "Status": 200,
    "Response": "{'Customer':'2311569'}"
  ], 3.0)
  ...

Availability: iOS XCUITest automation testing only.

Register a single block (in the application under test) that will be invoked when an XCUITest automation test case has sent a message using the APLAutomationSendMessage function. The -[APLConfiguration allowInvalidSignatures] method in the application under test must return YES for the message to be processed. See also APLAutomationSendMessage.

Objective-C example

APLAutomationMessageReceivedBlock(^NSObject* (NSString* name, id data) {
    if ([name isEqualToString: @"SetResponseData"]) {
        [MockedHttpInterceptor setResponse: data];
    }
    return nil;
});

Swift example

APLAutomationMessageReceivedBlock { (name: String, data: Any) -> NSObject in
    if name == "SetResponseData" {
        MockedHttpInterceptor.setResponse(data)
    }
    return nil
}

Availability: All.

If logLevel is APLLogLevelDebug and logging is enabled (see also APLSetLogging) then logs msg with optional parameters to the console. If logLevel is APLLogLevelError then logs msg with optional parameters to the console even if logging is disabled. You should prefer to use APLDEBUG or APLERROR macros for Objective-C. See also APLLogS for Swift.

Availability: All.

If logLevel is .debug and logging is enabled (see also APLSetLogging) then logs msg to the console. If logLevel is .error then logs msg the console even if logging is disabled. See also APLLog for Objective-C.

Availability: All.

When YES, Appfigurate library debugging messages will be output to the console. The default is NO. It is best practice to distribute applications via TestFlight and the App Store with logging set to NO. Also see APLLogging key in the Info.plist file.