iOS SDK Access

Prerequisites

• Before using the SDK, you need to register a HUAWEI ID and create an iOS app on the App Monitoring page.

Transport Protocol

HTTPS

Version Updates

Procedure

1. Integrate the access SDK.

   Method 1: Using CocoaPods

   • Add the official CocoaPods repository to the Podfile.

     source 'https://github.com/CocoaPods/Specs.git'

   • Add dependencies to the Podfile.

     pod 'APMSDK', '2.0.8'

   • Run the following command on the device:

     pod install --repo-update

   Method 2: Manual integration

   • Decompress the downloaded SDK to a specified directory. Note: Decompress the package only.
   • Add the decompressed xcframework static library to your project. Ensure that the xcframework static library to be imported is in the same disk space as the workspace. If not, select Copy items if needed and Create groups to copy the xcframework library file to the workspace.

2. Add a configuration file.

   During the creation of the iOS app, a configuration file named apm-sdk-config.json is generated. Download and drag the file to the root directory of the Xcode project, as shown in the following figure.

   

   Table 2 Configuration parameters

   Parameter	Mandatory	Default Value	Description
   appId	Yes	-	Mobile app ID.
   authorization	Yes	-	Used for app authentication.
   region	Yes	-	Region where APM is deployed. Currently, cn-north-4 is supported.
   uid	No	-	Custom ID.
   tag	No	-	Custom tag. Use commas (,) to separate multiple tags.
   url	No	-	Public domain name for reporting data to APM.
   networkWhiteList	No	-	Network monitoring whitelist.
   cacheThreshold	No	200	When the number of logs stored in the local database reaches this threshold, an alarm is reported. Value range: 30 to 1,000.
   timeInterval	No	60s	Interval for triggering reporting. Value range: 60 to 1,800, in seconds.
   reportBackground	No	true	Whether to report logs upon app backend switching.
   reportLaunch	No	false	Whether to report logs upon app startups. To enable this function, start the SDK before sending UIApplicationDidFinishLaunchingNotification.
   enableNetwork	No	false	Whether to enable network collection.
   enableCrash	No	false	Whether to enable crash collection.
   enableLaunch	No	false	Whether to enable startup collection.
   enableANR	No	false	Whether to enable ANR collection.
   enableError	No	false	Whether to enable error collection.
   enableDevice	No	false	Whether to enable device collection.
   enableEvent	No	false	Whether to enable custom statistics reporting.
   traceType	No	apm	Whether to enable open tracing. If this function is enabled, OpenTelemetry will be used. If this function is disabled, APM tracing will be used.
   logLevel	No	off	Debug log level. Options: debug, info, warn, error, and off.
   samplingRate	No	1.0	Sampling rate. Range: 0–1.0.

3. Start the SDK.
   • Objective-C code example

     @import APMSDK;
      
     // Start the SDK based on the apm-sdk-config.json configuration file.
     [APMSDK start];
     
     // Set a custom ID. You can also add an ID to the configuration file.
     [APMSDK setUid:@"Custom ID"];
     
     // Set a custom tag. You can also add a tag to the configuration file.
     [APMSDK addTag:@"Custom tag 1,Custom tag 2,Custom tag 3"];

   • Swift code example

     import APMSDK
     
     // Start the SDK based on the apm-sdk-config.json configuration file.
     APMSDK.start()  
     
     // Set a custom ID. You can also add an ID to the configuration file.
     APMSDK.setUid ("Custom ID")
     
     // Set a custom tag. You can also add a tag to the configuration file.
     APMSDK.addTag ("Custom tag 1, Custom tag 2, Custom tag 3")

4. Configure custom statistics reporting.

   Method	Description
   + (BOOL)event:(NSString *)key value:(id)value;	key: event name. Max.: 2,048 characters. value: event content. Valid JSON objects such as NSString, NSArray, NSDictionary, and NSNumber are supported. Max.: 30,720 characters.

   Objective-C code example

   // Event statistics
   [APMSDK event:@"User Information" value:@{@"name":@"XXX"}];
   [APMSDK event:@"Error Description" value:@"The request timed out."];
   [APMSDK event:@"Call Stack" value:@[@"0x0000000101ee9c6c", @"0x0000600000e61d80"]];
   
   // Numeric statistics
   [APMSDK event:@"Custom Load Time" value:@(0.238)]; 
   [APMSDK event:@"Purchase Statistics" value:@(1)];

   Swift code example

   // Event statistics
   APMSDK.event("User Information", value: ["name": "XXX"])
   APMSDK.event("Error Description", value: "The request timed out.")
   APMSDK.event("Call Stack", value: ["0x0000000101ee9c6c", "0x0000600000e61d80"])
   
   // Numeric statistics
   APMSDK.event("Custom Load Time", value: 0.238)
   APMSDK.event("Purchase Statistics", value: 1)

5. Configure identity authentication for network requests (applicable only when network request monitoring is enabled): When a request is sent to protected resources on the server, the process of challenging a user to prove their identity is triggered. The app needs to implement the APMURLProtocolDelegate protocol to complete this process.

   Objective-C code example

   @interface AppDelegate : UIResponder <UIApplicationDelegate, APMURLProtocolDelegate>
   
   @end
   
   @implementation APMAppDelegate
   
   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       //Set a proxy for identity authentication challenge.
       [APMURLProtocol setDelegate:self];
       // Start the SDK.
       [APMSDK start];
   }
   
   #pragma mark -- APMURLProtocolDelegate
   
   - (BOOL)APMURLProtocol:(APMURLProtocol *)protocol canAuthenticateAgainstProtectionSpace:(NSURLProtectionSpace *)protectionSpace {
       // Authenticate the server identity: The following shows an example. Perform operations based on the original authentication mode of the app.
       return [[protectionSpace authenticationMethod] isEqual:NSURLAuthenticationMethodServerTrust];
   }
   
   - (void)APMURLProtocol:(APMURLProtocol *)protocol didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge {
       //Trust the server identity: The following shows an example. Perform operations based on the original authentication mode of the app.
       NSURLCredential *credential = [NSURLCredential credentialForTrust:challenge.protectionSpace.serverTrust];
       [protocol resolveAuthenticationChallenge:challenge withCredential:credential];
   }
   
   - (void)APMURLProtocol:(APMURLProtocol *)protocol didCancelAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge {
   }
   
   @end

   Swift code example:

   class APMAppDelegate: UIResponder, UIApplicationDelegate, APMURLProtocolDelegate {
   
       func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
       //Set a proxy for identity authentication challenge.
           APMURLProtocol.setDelegate(self)
          // Start the SDK.
           APMSDK.start()
       }
   
       func apmurlProtocol(_ `protocol`: APMURLProtocol, canAuthenticateAgainstProtectionSpace protectionSpace: URLProtectionSpace) -> Bool {
   	// Authenticate the server identity: The following shows an example. Perform operations based on the original authentication mode of the app.
           return protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust
       }
   
       func apmurlProtocol(_ `protocol`: APMURLProtocol, didReceive challenge: URLAuthenticationChallenge) {
           //Trust the server identity: The following shows an example. Perform operations based on the original authentication mode of the app.
           if let serverTrust = challenge.protectionSpace.serverTrust {
               let credential = URLCredential(trust: serverTrust)
               `protocol`.resolve(challenge, with: credential)
           }
           else {
               `protocol`.resolve(challenge, with: nil)
           }
       }
   
       func apmurlProtocol(_ `protocol`: APMURLProtocol, didCancel challenge: URLAuthenticationChallenge) {
   
       }
   }

Data Reporting Policy

The SDK supports the following log reporting policies: threshold-based reporting, scheduled reporting, reporting when the app is switched to the backend, and reporting upon startup. Set parameters such as cacheThreshold, timeInterval, reportBackground, and reportLaunch based on the scenario.

Enabling Log Debugging

Enable log debugging if needed. Then you can monitor SDK running in real time based on logs, and make adjustments accordingly. The log level can be debug, info, warn, error, or off (disabled).

Disable log debugging before bringing an app online. That is, set the log level to off.

Example: Set the log level in the apm-sdk-config.json configuration file.