Integration Guide QdsInappWrapperLib for Android

The integration of QdsInappWrapperLib takes place in the same way as IOLib (see Integration Guide Android)

Integration with Android Studio (or IntelliJ IDEA)

The QdsInappWrapperLib is imported as an Android Library Project (.aar). To do this, copy the file qdsInappWrapperLib-xxx.aar to the libs folder of the application module.

The library itself and google-play-services (at least version 4.1.32) must be added to the build.gradle file of the application module as dependencies:

dependencies {
  compile(name: ’qdsInappWrapperLib-2.7.0’, ext:'aar')
  compile 'com.google.android.gms:play-services:4.1.32'
  ...
}

Add the following entry to the property repositories to include the dependency correctly:


repositories {
   ...
   flatDir {
      dirs 'libs'
   }
}

The library must be in the libs folder of the project, otherwise the path will not match.

Integration in Eclipse

As part of the transition to the Gradle build system and the release of Android Studio, Google does not officially support the import of .aar files into Eclipse.

There is an unofficial method using the gradle-eclipse-aar-plugin  
(see: https://github.com/ksoichiro/gradle-eclipse-aar-pluginhttps://github.com/ksoichiro/gradle-eclipse-aar-plugin)

Important:

The following information must be entered in AndroidManifest.xml of the app:

If IOLib is already included, the permissions must have been set beforehand. Enter the following permissions into the file AndroidManifest.xml, if none are present.

<-- required permissions for the Library -->
<uses-permission android:name="android.permission.INTERNET" />

<-- Optional start -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<-- Optional end -->
...
<application>
   ...
   <-- required meta-data for the Library -->
   <meta-data android:name="com.google.android.gms.version"
      android:value="@integer/google_play_services_version" />
   ...
</application>

To ensure the correct display of the survey dialogue after screen rotation, add two further properties to the corresponding activity (which calls the QdsInappWrapperLib):


<activity
   …
   android:launchMode="singleTop"
   android:configChanges="orientation|screenSize"
>
  …
</activity>

INFO: From the (minimal) API level 11 (Android 3.0), setting the property android:configChanges is no longer required.

Integration of the return address (optional)

The return to the app takes place by registration of a custom URL scheme. Add an intent filter to the corresponding activity for this purpose:

<activity
      …
      android:launchMode="singleTop"
      android:configChanges="orientation|screenSize">

   …
   <intent-filter>
      <action android:name="android.intent.action.VIEW"/>
      <category android:name="android.intent.category.DEFAULT"/>
      <category android:name="android.intent.category.BROWSABLE"/>
      <data android:scheme="offeridentifier" />
   </intent-filter>
</activity>

The term offerIdentifier must be replaced by an RFC 3986 compatible URI scheme (see: http://tools.ietf.org/html/rfc3986#page-17).
The identifier assigned by ÖWA is used as the basis: e.g. at_a_oewa. All underscores _ must be removed from this string. For the specific example this results in the following URI scheme:


  <data android:scheme="ataoewa" />

This special case only applies to the intent filter.

Functionality

The QdsInappWrapperLib is represented by the class QdsInappWrapper. A concrete instance of this class is created with:

new QdsInappWrapper(Activity activity);

The QdsInappWrapperLib must be initialized when calling the app. This takes place by way of the above-mentioned call. MainActivity should be passed on for activity. To enable display of a survey invitation, the method

startSession(String offerIdentifier, String countryCode);

must be called for the instance; e.g. in the MainActivity of the method onStart(). The offerIdentifier and country code (with "at") must be passed on in this context. The parameter offerIdentifier is the unique identifier of the offer for the respective app. The offerIdentifieris assigned by ÖWA for each app and each operating system.

Important:

Any initial loading processes should ideally be completed at the start of a session, since a poll invitation may be displayed immediately after calling startSession().

QdsInappWrapper qdsInappWrapper = new QdsInappWrapper(this); qdsInappWrapper.startSession("offerIdentifier", "at");

If loading dialogues are shown when starting the app, startSession() should only be called subsequently, since the invitation dialogue is displayed prematurely otherwise. Generally, calling startSession() means that a dialogue with a survey invitation may be displayed after calling of the method. startSession()should be called once the app is ready to display a questionnaire if needed. Generally, startSession() can be called repeatedly.

Notes:

The QdsInappWrapperLib should be initialized at the start of the "MainActivity". If this is not possible for technical or content reasons, a suitable alternative entry point is to be selected by the developer. The important factor is that the user must get the opportunity to interact with the corresponding activity and the potential survey dialogue.

The opt-out function is controlled by QdsInappWrapperLib via the survey invitation, so no further action is necessary for this. Survey and data protection information on the ÖWA study are optionally shown to the survey participant within the survey.

Test - Display dialogue window:

Please use the ÖWA-Checker to mark the device as a test device. The documentation for the ÖWA-Checker is available at http://www.oewa.at/oewa-checker.

Please check correct display of the survey invitation, clickability of all buttons, and opening of the questionnaire by clicking on the participate button.

The customer is responsible for installation of QdsInappWrapperLib in accordance with the valid guidelines of ÖWA. The customer is responsible for ensuring that the implementation of the library is correct even if the app is changed.