Starting an Android session

Starting a MobileFirst Quality Assurance session with the Android SDK entails three steps. First, build a configuration to define how MobileFirst Quality Assurance works with your app. Second, start the session itself. Third, add tracking to your activities.

Procedure

Build a configuration for MobileFirst Quality Assurance.
1. Add the following code snippet to the MainActivity class of your app, which is in the MainActivity.java file. It uses your application key to send data to MobileFirst Quality Assurance.
```
public static final String APP_KEY = "Your_Application_Key_Goes_Here";
```
  In the code snippet, replace the Your_Application_Key_Goes_Here variable with your application key from MobileFirst Quality Assurance. If you already have an account, you can find your app key in the MobileFirst Quality Assurance web page 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 Android SDK version 3.4.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.4.0, or later.
2. Add the following code snippet to the MainActivity class of your app, which specifies the URL of the MobileFirst Quality Assurance server to send data to. In the code snippet, replace the Your_Server_URL_Goes_Here variable with the URL of your MobileFirst Quality Assurance server.
```
public static final String SERVER_URL = "Your_Server_URL_Goes_Here";
```
3. To use the MobileFirst Quality Assurance configuration builder, first import the following items by adding them to the MainActivity class of your app:
```
import com.ibm.mqa.MQA;
import com.ibm.mqa.MQA.Mode;
import com.ibm.mqa.config.Configuration;
```
4. Optional: To enable your app to send log calls to MobileFirst Quality Assurance, add the following import statement to the MainActivity class:
```
import com.ibm.mqa.Log;
```
  With MobileFirst Quality Assurance, you can manually log events to the IBM MobileFirst™ Quality Assurance server. This log information can be useful when you are debugging problems or crash reports that users submit. You can track custom defined activities from your application.
  
  MobileFirst Quality Assurance comes with its own logging library, com.ibm.mqa.Log, that you can use in place of the standard Android logging library. This class mimics the standard android.util.Log class and has the same interfaces, including the Log.v, Log.d, Log.i, Log.w, and Log.e methods. Also, the MobileFirst Quality Assurance logging methods send your data to Logcat, the Android logging system.
5. Enable gathering user feedback. For instructions, see Enabling feedback on Android devices.
6. Optional: In preproduction mode, configure in-app bug reporting. For instructions, see Reporting bugs.
7. Create a configuration object in the onCreate event of your MainActivity class. This object provides several methods that you can use to specify configuration items. At the conclusion of configuring the object, you call a build() method to finalize the object. An example of a complete configuration follows:
```
Configuration configuration = new Configuration.Builder(this)
        .withAPIKey(APP_KEY) //Provides the quality assurance application APP_KEY
        .withMode(Mode.QA) //Selects the quality assurance application mode
        .withReportOnShakeEnabled(true) //Enables shake report trigger
        .withServerURL("SERVER_URL") //REQUIRED - Specifies the endpoint server that receives the data.
        .build();
```
  You can use the following methods with the configuration object:
  API key
  Required
  
  .withAPIKey(String APP_KEY)
  
  The API key is a string that contains your unique application key for MobileFirst Quality Assurance, which is available in the MobileFirst Quality Assurance pane. For more information about retrieving your application key, see Managing app settings.
  
  APP_KEY
  
  Your application key for MobileFirst Quality Assurance.
  Server URL
  Required
  
  .withServerURL(String SERVER_URL)
  
  The Server URL is a string that contains the URL for your MobileFirst Quality Assurance server.
  
  SERVER URL
  
  The URL of your MobileFirst Quality Assurance server, for example, https://your_company.example.com.
  Preproduction or production mode
  .withMode(Mode.mode)
  
  Use this method to switch between preproduction mode (Mode.QA) and production mode (Mode.MARKET). For more information about the differences between the preproduction and production modes, see Differences between preproduction and production modes.
  
  Mode.QA
  
  Use this parameter to activate preproduction mode.
  
  Mode.MARKET
  
  Use this parameter to activate production mode.
  In-app bug reports
  Optional
  
  .withReportOnShakeEnabled(true)
  
  With MobileFirst Quality Assurance, you can enable and disable bug reporting when users shake the device. When this feature is disabled, bug reports can be triggered only by using a widget that MobileFirst Quality Assurance automatically creates on the widget pane. This setting pertains only to preproduction mode and has no effect in production mode. For more information about in-app bug reports, see Reporting bugs on Android devices.
  
  withReportOnShakeEnabled
  
  A Boolean value. When the value is set to true, MobileFirst Quality Assurance creates a bug report when the user shakes the mobile device and triggers the accelerometer. When the value is set to false, the user must use a bug report widget that is placed on the widget pane. The default value is false.

In the MainActivity class of your app, add code to configure and start MobileFirst Quality Assurance sessions.

Tell MobileFirst Quality Assurance to start a new session by calling the MQA.startNewSession() method in the onCreate event of your MainActivity class.

Prototype

MQA.startNewSession(this, configuration);

Example

import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;

// Make sure that you import the quality assurance application
import com.ibm.mqa.MQA;
import com.ibm.mqa.MQA.Mode;
import com.ibm.mqa.config.Configuration;

// Optionally import the quality assurance application's logging functions
import com.ibm.mqa.Log;

public class MainActivity extends AppCompatActivity {

    public static final String APP_KEY = "Your_Application_Key_Goes_Here";
    public static final String SERVER_URL = "Your_Server_URL_Goes_Here";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        Configuration configuration = new Configuration.Builder(this)
                .withAPIKey(APP_KEY) //Provides the quality assurance application APP_KEY
                .withMode(Mode.QA) //Selects the quality assurance production mode.  This example is for preproduction mode, 
			//Use .withMode(Mode.MARKET) for production mode.
                .withReportOnShakeEnabled(true) //Enables shake report trigger in preproduction mode. In production mode it has no effect.
                .withServerURL(SERVER_URL) //REQUIRED - Specifies the endpoint server that receives the data.
                .build();

        MQA.startNewSession(this,configuration);
    }
}

Track App activities.
Note: Tracking app activities is necessary only in preproduction mode. However, these methods exist in the production library as a convenience for switching between the two libraries.