Integration Guide QdsInappWrapperLib für Android

Die Einbindung der QdsInappWrapperLib erfolgt analog zur IOLib (siehe Implementierung Android App).

Einbindungsmöglichkeit in Android Studio (oder IntelliJ IDEA)

Die QdsInappWrapperLib wird als Android Library Project (.aar) importiert. Dazu wird die Datei qdsInappWrapperLib-xxx.aar in den Ordner libs des Anwendungsmoduls kopiert.

In der Datei build.gradle des Anwendungsmoduls müssen die Library selbst und die google-play-services (mind. Version 4.1.32) als Abhängigkeit hinzugefügt werden:

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

Damit die Abhängigkeit korrekt eingebunden werden kann, muss zur Eigenschaft repositories folgender Eintrag hinzugefügt werden:


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

Dabei muss die library im libs Ordner des Projektes liegen, da sonst der Pfad nicht passt.

Einbindungsmöglichkeit in Eclipse

Im Zuge der Umstellung auf das Gradle-Buildsystem und der Veröffentlichung von Android Studio,

gibt es seitens Google keine offizielle Unterstützung für den Import von .aar-Dateien in Eclipse.
Einen inoffiziellen Weg bietet z.B. das gradle-eclipse-aar-plugin
(siehe: https://github.com/ksoichiro/gradle-eclipse-aar-plugin).

Wichtig:
Folgende Informationen müssen in AndroidManifest.xml der App eingetragen werden:

Sollte die IOLib bereits eingebunden sein, müssen die Permissions schon gesetzt sein.
Die folgenden Permissions sind in der Datei AndroidManifest.xml einzutragen, falls keine von diesen vorhanden sind.

<-- 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>

Um die korrekte Anzeige des Befragungsdialogs nach Bildschirmrotation zu gewährleisten, sollten in der entsprechenden Activity (welche die QdsInappWrapperLib aufruft) noch zwei weitere Eigenschaften ergänzt werden:


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

INFO: Ab dem (minimalen) API-Level 11 (Android 3.0) kann auf das Setzen der Eigenschaft android:configChanges verzichtet werden.

Integration der Rücksprungadresse (optional)

Der Rücksprung zur App geschieht durch das Registrieren eines Benutzerdefinierten-URL-Schemas.

Dabei muss zur entsprechenden Activity ein Intent-Filter hinzugefügt werden:

<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>

Der Ausdruck offerIdentifier muss durch ein RFC 3986 kompatibles URI Schema ersetzt werden (siehe hierzu: http://tools.ietf.org/html/rfc3986#page-17).
Als Basis wird der von der ÖWA vergebene Kennzeichner genommen: bspw. at_a_oewa. Aus dieser Zeichenkette müssen alle Unterstriche _ entfernt werden. Für das konkrete Beispiel lautet das Schema im Intent-Filter:


  <data android:scheme="ataoewa" />

Dieser Sonderfall gilt nur für den Intent-Filter.

Funtionsweise

Die QdsInappWrapperLib wird durch die Klasse QdsInappWrapper repräsentiert. Eine konkrete Instanz dieser Klasse wird erzeugt mit:

new QdsInappWrapper(Activity activity);

Die QdsInappWrapperLib muss beim Aufruf der App initialisiert werden. Dieses geschieht über den oben erwähnten Aufruf. Für activity sollte die MainActivity übergeben werden. Um das Anzeigen einer Befragungseinladung zu ermöglichen muss die Methode

startSession(String offerIdentifier, String countryCode);

an der Instanz aufgerufen werden; z.B. in der MainActivity in der Methode onStart(). Hier müssen der offerIdentifier und der Ländercode (mit "at") übergeben werden. Der Parameter offerIdentifier ist die eindeutige Kennung des Angebots der jeweiligen App. Der offerIdentifier wird von der ÖWA
pro App und pro Betriebssystem eindeutig vergeben.

Wichtig:

Beim Start einer Session sollten im besten Fall alle anfänglichen Ladeprozesse abgeschlossen sein,
da unmittelbar nach dem Aufruf von startSession() eine Befragungseinladung angezeigt werden kann.

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

Falls beim Start der App Ladedialoge angezeigt werden, sollte startSession() erst im Anschluss aufgerufen werden, da sonst der Dialog mit der Einladung zu früh angezeigt werden kann. Generell bedeutet der Aufruf von startSession(), dass nach dem Aufruf der Methode ein Dialog mit einer Befragungseinladung angezeigt werden kann. startSession() sollte dann aufgerufen werden, wenn die App bereit ist, bei Bedarf einen Fragebogen anzuzeigen. Grundsätzlich kann startSession() immer wieder aufgerufen werden.

Hinweise:

Die Initialisierung der QdsInappWrapperLib sollte beim Start der „MainActivity“ geschehen. Falls dies aus technischen oder inhaltlichen Gründen nicht möglich ist, muss als Alternative ein geeigneter Einstiegspunkt vom Entwickler gewählt werden. Wichtig ist, dass der Benutzer die Möglichkeit bekommt mit der entsprechenden Activity und dem potentiellen Umfragedialog zu interagieren.

Die Opt-Out-Funktion wird von der QdsInappWrapperLib über die Befragungseinladung gesteuert, somit ist dafür keine weitere Aktion notwendig. Studien- und Datenschutzinformationen zur ÖWA Studie werden dem Befragungsteilnehmer innerhalb der Befragung bei Bedarf zur Verfügung gestellt.

Test-Einblendung Dialogfenster:

Um das Gerät als Testgerät zu markieren, verwenden Sie bitte den ÖWA-Checker. Die Dokumentation zum ÖWA-Checker erhalten Sie unter http://www.oewa.at/oewa-checker

Bitte überprüfen Sie die Einblendung des Befragungsfensters, die Klickbarkeit aller Schaltflächen sowie das Öffnen des Fragebogens durch einen Klick auf die Teilnehmen Schaltfläche.

Der Kunde ist für den Einbau der QdsInappWrapperLib im Einklang mit den jeweils gültigen Richtlinien der ÖWA verantwortlich. Der Kunde ist dafür verantwortlich, dass auch bei einer Änderung der App die Implementierung der Library korrekt ist.