Starting an iOS session

When your application starts, you must indicate to MobileFirst Quality Assurance that you are starting a new session. This process includes two steps. First, specify the settings that are related to the way that MobileFirst Quality Assurance works with your app. Second, start the session.

1. Locate the didFinishLaunchingWithOptions method in your AppDelegate file:

   Objective-C

   AppDelegate.m file

   Swift

   AppDelegate.swift file

2. Start the MobileFirst Quality Assurance session.

   Objective-C

   1. Start the new session in a method within your applicationDelegate method, such as the didFinishLaunchingWithOptions method. You can find your delegate by opening the folder with the same name as your project in the Project Navigator. Look for the projectDelegate.m file, where project is the project name.
   2. Add the following code inside the didFinishLaunchingWithOptions method to start a new session:

      // Starts a quality assurance session using a placeholder key and QA mode
      	[MQALogger startNewSessionWithApplicationKey:@"Your_Application_Key"];

   3. Replace the Your_Application_Key variable with your application key from MobileFirst Quality Assurance.
      Tip: If you already have an account, you can find your app key in the MobileFirst Quality Assurance web pane under App Settings.
      Restriction: For an app that is already instrumented for MobileFirst Quality Assurance using an older version of the SDK to use the features that are included in iOS SDK version 3.3.0, and later, you must regenerate and replace your app key. For more information about how to regenerate your app key, see Managing app settings. App keys that were generated earlier than February 2016 continue to work with the older SDK, but no longer work after you upgrade your SDK to version 3.3.0, or later.
   4. Specify the URL of your MobileFirst Quality Assurance server to send data to the server by adding the following code inside the didFinishLaunchingWithOptions method:

          [[MQALogger settings] setServerURL:@"Your_Server_URL"];

      The variable Your_Server_URL is the URL of your MobileFirst Quality Assurance server (for example, https://your_server.example.com).
      Tip: Ensure that your URL correctly included https or http according to your installation of MobileFirst Quality Assurance.

   Swift

   1. Locate the didFinishLaunchingWithOptions method in the AppDelegate.swift file.
   2. Add the following code inside the application, where Your_Application_Key is a valid key for your app:

      // Set the application key
      MQALogger.startNewSessionWithApplicationKey("Your_Application_Key")

      Restriction: For an app that is already instrumented for MobileFirst Quality Assurance using an older version of the SDK to use the features that are included in iOS SDK version 3.3.0, and later, you must regenerate and replace your app key. For more information about how to regenerate your app key, see Managing app settings. App keys that were generated earlier than February 2016 continue to work with the older SDK, but no longer work after you upgrade your SDK to version 3.3.0, or later.
   3. Specify the URL of your MobileFirst Quality Assurance server by adding the following code inside the didFinishLaunchingWithOptions method:

      // Set the server URL
      MQALogger.settings().serverURL="Your_Server_URL"

      The variable Your_Server_URL is the URL of your MobileFirst Quality Assurance server (for example, https://your_server.example.com).
      Tip: Ensure that your URL correctly included https or http according to your installation of MobileFirst Quality Assurance.

3. Define whether to use preproduction mode or production mode. For information about the differences between preproduction and production mode, see Differences between preproduction and production modes.

   Objective-C

   1. Locate the didFinishLaunchingWithOptions method.
   2. Add one of the following lines of code inside the didFinishLaunchingWithOptions method:
      • To use preproduction mode, add this line of code: [[MQALogger settings] setMode:MQAModeQA];
      • To use production mode, add this line of code: [[MQALogger settings] setMode:MQAModeMarket];
      Tip: You can use build settings to compile your code to use one mode or the other. For example, if you define a Debug build setting, then you can compile your code with preproduction (QA) mode when the Debug build is used:

      #ifdef Debug
      [[MQALogger settings] setMode:MQAModeQA];
      #else
      [[MQALogger settings] setMode:MQAModeMarket];
      #endif

   Swift

   1. In the AppDelegate.swift file, search for the didFinishLaunchingWithOptions method.
   2. Add one of these lines of code inside the didFinishLaunchingWithOptions method:
      • To use preproduction mode, add the following line of code: MQALogger.settings().mode = MQAMode.QA
      • To use production mode, add the following line of code: MQALogger.settings().mode = MQAMode.Market
      You can use #if statements and a preprocessor macro to switch between modes by completing these steps:

      1. Add following code in the didFinishLaunchingWithOptions method:

                 //Set the SDK mode Market vs QA for Production and Pre-Production
                 #if Debug
                     MQALogger.settings().mode = MQAMode.QA
                 #elseif Release
                     MQALogger.settings().mode = MQAMode.Market
                 #endif

      2. Set the Swift Compiler Custom Flags:
         1. Select the app project, and go to the Build Settings page.
         2. In the Search field, enter Swift Compiler.
         3. Under the Swift Compiler - Customer Flags section, set -D Debug for the Debug flag and -D Release for the Release flag.
         
   3. Edit the project build configuration by completing the following steps:
      1. Select the project in Xcode, and then click Product > Scheme > Edit Schema.
      2. On the Edit Schema page, select Debug from the list to set the build mode to QA mode.
      3. On the Edit Schema page, select Release from the list to set the build mode to Market mode.
      
   4. Recompile the project. Selecting Debug build mode sets the SDK mode to QA, and selecting Release build mode sets the SDK mode to Market.

4. Optional: If you are using QA (preproduction) mode, enable bug reporting and feedback. In preproduction mode, the MobileFirst Quality Assurance SDK for iOS supports in-app bug reporting and user feedback. When you complete the steps, MobileFirst Quality Assurance users can report bugs and give feedback to the MobileFirst Quality Assurance server in two ways:
   • Call the MQALogger.showReportScreen() API method to start the Show Report screen from the app.
   • Shake the device:
     • On a real device (iPhone, iPad, iPod), start the app, and then shake the device.
     • On a simulator (defined in Xcode as the target), select Hardware > Shake Gesture.
     The setting for the shake gesture is set to YES (for Objective-C) or true (for Swift) by default, but you can disable the shake feature for generating bug reports by adding the following setting to the correct file:

     Objective-C

     Add the following line to your AppDelegate.m file before the code to start the session:

     [[MQALogger settings] setReportOnShakeEnabled:NO];

     Swift

     Add the following line to your AppDelegate.swift file before the code to start the session:

     MQALogger.settings().reportOnShakeEnabled = false

5. Optional: If you are working in production (Market) mode, enable app feedback. With MobileFirst Quality Assurance, users can send feedback either programmatically from the app code or interactively from the mobile device. Use the following APIs to enable app feedback in production mode:

   • MQALogger.feedback()

     This method opens a default feedback window for users to provide the feedback in.

   • MQALogger.feedback("User feedback.");

     This method opens a feedback window titled User feedback.

   • MQALogger.feedback("User Feedback", placeholder:"Provide your feedback here.")

     This method brings up a customized feedback window with the title "User Feedback" and a text "Provide your feedback here".

   • MQALogger.sendFeedback("Feedback send from app.")

     This method does not open the feedback window. It sends the feedback text silently without user interaction.

6. Optional: The feature that device owners can use to report bugs by shaking the device can be enabled or disabled. By default, you can trigger user feedback in the preproduction mode when users shake the device and trigger the accelerometer. Shaking the device to start user feedback is part of the typical MobileFirst Quality Assurance bug reporting flow. To enable or disable this method for triggering feedback, modify the following setting before you start a MobileFirst Quality Assurance session:

   Objective-C

   Add this line:

   [[MQALogger settings] setReportOnShakeEnabled:YES];

   Swift

   Add this line:

   MQALogger.settings().reportOnShakeEnabled = true

   By default, this method is set to YES (for Objective-C) or true (for Swift). To disable the shaking trigger, set the value of the method to NO or false.
7. Optional: Enable crash reporting by completing the following steps after the content that you added to start your new session:

   Objective-C

   Add this line:

   NSSetUncaughtExceptionHandler(&MQAUncaughtExceptionHandler);

   The following code snippet shows the complete didFinishLaunchingWithOptions method:

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
   {
       // Override point for customization after application launch.
       if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad) {
           UISplitViewController *splitViewController = (UISplitViewController *)self.window.rootViewController;
           UINavigationController *navigationController = [splitViewController.viewControllers lastObject];
           splitViewController.delegate = (id)navigationController.topViewController;
       }
    
       [[MQALogger settings] setServerURL:@"https://your_server.example.com"];
   
      #ifdef Debug
      [[MQALogger settings] setMode:MQAModeQA];
      #else
      [[MQALogger settings] setMode:MQAModeMarket];
      #endif
       
       // Starts a quality assurance session using a placeholder key
       [MQALogger startNewSessionWithApplicationKey:@"Your-Application-Key-Goes-Here"];
    
       // Enables the quality assurance application crash reporting 
       NSSetUncaughtExceptionHandler(&MQAUncaughtExceptionHandler);
       return YES; }

   Swift

   Complete the following steps:

   1. Create a header file (for example, MQAExceptionHandler.h) and add the following two lines in it:

      volatile void exceptionHandler(NSException *exception);
      extern NSUncaughtExceptionHandler *exceptionHandlerPointer;

      Your header file looks like the following example:

          #ifndef MQASampleAppiOSSwift_MQAExceptionHandler_h
          #define MQASampleAppiOSSwift_MQAExceptionHandler_h
          volatile void exceptionHandler(NSException *exception);
          extern NSUncaughtExceptionHandler *exceptionHandlerPointer;
          #endif

   2. Create an Objective-C class (for example, MQAExceptionHandler.m).
   3. If you are prompted to configure an Objective-C bridging header, click Yes. This action configures the new class to use the same bridging header.
      
      Note: If you do not already have a bridging header file, a bridging header file is generated in the project folder.

      If you already have a bridging header file, then a copy of the file is generated. One file is located in the project folder and the other is in the project root.

      
   4. Add an implementation to MQAExceptionHandler.m. You can implement the MQAExceptionHandler method anyway that you want. However, you must add an Objective-C pointer for that method by adding the following lines in the new Objective-C class:

      void exceptionHandler(NSException *exception) {}
      NSUncaughtExceptionHandler *exceptionHandlerPointer = &exceptionHandler;

   5. Add the Objective-C class to your bridging header by adding the following line:

      #import "MQAExceptionHandler.h"

   6. Enable the crash report. In the AppDelegate.swift file, enable crash reporting by adding the following line at the end of the application(_:didFinishLaunchingWithOptions:) method:

      NSSetUncaughtExceptionHandler(exceptionHandlerPointer)

      • An example of the code is:

            func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        
                //Set the SDK mode Market vs QA for Production and Pre-Production
                #if Debug
                MQALogger.settings().mode = MQASettingsMode.QA
                #elseif Release
                MQALogger.settings().mode = MQASettingsMode.Market
                #endif
        
                // Set the server URL
                MQALogger.settings().serverURL="your_server_URL"
        
                // Set the application key
                MQALogger.startNewSessionWithApplicationKey("Your_Application_Key")
        
                //Enable MQA Crash report detection
                NSSetUncaughtExceptionHandler(exceptionHandlerPointer)
                // Override point for customization after application launch.
                return true
            }

      If your app crashes, the exception information is captured and sent to the MobileFirst Quality Assurance server through the NSSetUncaughtExceptionHandler() method.

8. Add MobileFirst Quality Assurance logging. The following logging methods are available in the SDK:
   • MQALogger.log (message: String!)

     For example, add this line: MQALogger.log ("This is a MQA log").

   • MQALogger.log (message: String!, withLevel: MQALogLevel), where MQALogLevel is one of the following options:
     • MQALogLevelFatal
     • MQALogLevelError
     • MQALogLevelWarning
     • MQALogLevelInfo
     • MQALogLevelVerbose

   For example, add this line: MQALogger.log ("MQA log with MQALogLevelError", withLevel: MQALogLevelError).

9. Optional: Simulate an app crash. If your app crashes, the SDK catches the exception and sends it to the MobileFirst Quality Assurance server. You might want to simulate an app crash to test this feature. Use the following techniques to simulate a crash:
   • Stop the app from the code. For example, when a button is pressed, you call exit(1).
   • Add a UI control to the app that does not exist. For example, add a button and implement the buttonPressed method. Then, remove the button, and replace it with a button with the same name. Xcode does not remove the old reference. As a result, an exception is generated when the new button is pressed because the code still refers to the button that was removed.