Instrukcja integracji Android

Biblioteka w formacie aar jest dostępna pod adresem: http://www.appmanago.pl/api/developers/

Przykład konfiguracji dla Gradle:

Aby dołączyć bibliotekę do projektu należy umieścić plik aar w katalogu libs, a następnie
zmodyfikować plik gradle.build.
Parametr ‘name’ w sekcji ‘compile’ musi być taki, jak nazwa pliku biblioteki bez rozszerzenia.

repositories {
  flatDir {
    dirs 'libs'
  }
}
dependencies {
  compile(name:'appmanagolibrary-release', ext:'aar')
}

Dla innych narzędzi sprawdź dokumentację w jaki sposób można dodać zewnętrzne biblioteki

Konfiguracja biblioteki

W pliku strings.xml integrowanej aplikacji należy dodać poniższe wpisy:

  • appmanago_launch_time Definiuje czas odstępu pomiędzy kolejnymi użyciami modułu/funkcji po którym uznajemy, że aplikacja została uruchomiona ponownie. Wartość podawana jest w minutach.
    <string name="appmanago_launch_time">30</string>

    Dla wartości 30 – kolejne użycie aplikacji zostanie zliczone w momencie, gdy po 30 minutach niekorzystania z aplikacji zostanie ona ponownie uruchomiona.

  • appmanago_sync_meantime Definiuje, co jaki czas ma być wykonywana próba synchronizacji zdarzeń, które zaszły podczas braku połączenia z Internetem i czekają na wysyłkę. Wartość podawana jest w minutach.
    <string name="appmanago_sync_meantime">360</string>

    W przykładzie próby synchronizacji zdarzeń będą wywoływane co 360 minut.

  • appmanago_endpoint Definiuje endpoint (Adres strony)na jaki wysyłane są zapytania.
    Dla APPmanago domyślnym jest:
    <string name="appmanago_endpoint">https://click.appmanago.com</string>
  • appmanago_vendor_id Identyfikator vendora, można go znaleźć po zalogowaniu w systemie APPmanago w panelu Ustawienia -> Konto. Jest to ciąg znaków identyfikujący dane konto APPmanago
    <string name="appmanago_vendor_id">VENDOR_ID</string>
  • appmanago_application_id Proste ID aplikacji dodanej w systemie. Należy je utworzyć podczas tworzenia aplikacji w APPmanago.
    <string name="appmanago_application_id">APLIKACJI_SIMPLE_ID</string>
  • appmanago_sender_idIdentyfikator konta wysyłkowego GCM. Generuje się go przy tworzeniu konta GCM w serwisie Google. Więcej na ten temat – w sekcji Integracja z Google Cloud Messaging.
    <string name="appmanago_sender_id">SENDER_ID</string>
  • appmanago_gps_sync_timeOdstęp czasowy między automatycznym wysłaniem pozycji gps (minuty).
    <string name="appmanago_gps_sync_time">1</string>

Przesyłanie zdarzeń do APPmanago

Komunikacja zdarzeń odbywa się przez interfejs AmMonitoring. Inicjacja takiego obiektu może wyglądać jak poniżej i odbywać się w metodzie onCreate().

private AmMonitoring amMonitor;
amMonitor = AmMonitor.initLibrary(getApplicationContext());

Obiekty amMonitor należy tworzyć per moduł, ponieważ zawierają one logikę odpowiedzialną za mierzenie czasu w którym moduł (Activity) jest używany.

Dodatkowo należy dodać nadpisanie metod onResume() i onPause(), które potrzebne są do mierzenia czasu spędzonego w danym module. Nazwa modułu musi być taka sama jak ta zdefiniowana w APPmanago.

@Override
  protected void onResume() {
    super.onResume();
    amMonitor.eventStarted(NAZWA_MODUŁU, new AmProperties());
  }

  @Override
  protected void onPause() {
    super.onPause();
    amMonitor.eventEnded(NAZWA_MODUŁU, new AmProperties());
  }

Integracja z Google Cloud Messaging (GCM)

Aby dodać obsługę GCM do aplikacji należy wykonać instrukcję ze strony Google:
https://developers.google.com/cloud-messaging/android/client

By dostać numery Server API Key i Sender ID należy zarejestrować aplikację podczas tworzenia konta GCM. Następnie wygenerowane ID należy dodać do ustawień konta GCM w APPmanago. Należy również do projektu androidowego dodać wygenerowany plik google-services.json

Kolejnym krokiem jest dodanie uprawnień i serwisów do AndroidManifest.xml:

    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
    <uses-permission android:name="<YOUR_API_PACKAGE>.permission.C2D_MESSAGE" />

    <permission
      android:name="<YOUR_API_PACKAGE>.permission.C2D_MESSAGE"
      android:protectionLevel="signature" />
    <receiver
        android:name="com.google.android.gms.gcm.GcmReceiver"
        android:permission="com.google.android.c2dm.permission.SEND">
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            <category android:name="com.appmanago.lib" />
        </intent-filter>
    </receiver>

    <service
        android:name="com.appmanago.lib.gcm.AmGcmListenerService"
        android:exported="false" >
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        </intent-filter>
    </service>

    <service
        android:name="com.appmanago.lib.gcm.AmInstanceIDListenerService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.android.gms.iid.InstanceID"/>
        </intent-filter>
    </service>

    <service
        android:name="com.appmanago.lib.gcm.AmRegistrationIntentService"
        android:exported="false">
    </service>

Klasa AmRegistrationIntentService jest uruchamiana automatycznie i wysyła wygenerowane RegistrationId do serwera. Można ją nadpisać jeśli istnieje taka potrzeba.

Dodatkowo do metody onCreate() należy sprawdzić obsługę Google api. Można to wykonać jak poniżej:

   
if (checkPlayServices()) {
        startService(new Intent(this, AmRegistrationIntentService.class));
    }

A implementacja wygląda następująco:

  private boolean checkPlayServices() {
    GoogleApiAvailability apiAvailability = GoogleApiAvailability.getInstance();
    int resultCode = apiAvailability.isGooglePlayServicesAvailable(this);
    if (resultCode != ConnectionResult.SUCCESS) {
        if (apiAvailability.isUserResolvableError(resultCode)) {
            apiAvailability.getErrorDialog(this, resultCode, 9000)
                    .show();
        } else {
            Log.i(Constants.LOG_TAG, "This device is not supported.");
            finish();
        }
        return false;
    }
    return true;
  }

Rich notification

Istnieje możliwość dodania do powiadomienia multimediów typu zdjęcie po zaznaczeniu przy tworzeniu powiadomienia flagi “Rich content” i uzupełnieniu nowe pola. Można dostosować to do swoich potrzeb bądź używać przykładu zaimplementowanego w bibliotece APPmanago. Domyślnie gdy wysyłamy powiadomienie z flagą rich notification z typem “jpg” bądź “png” i z adresem url do zdjęcia to zostanie ono wyświetlone pod powiadomieniem.

Aby dostosować do swoich potrzeb wyświetlanie rozbudowanych powiadomień należy nadpisać metodę richPushNotification() w klasie PushActionExecutor.
Żeby to osiągnąć należy do AndroidManifest.xml zmienić klasę com.appmanago.lib.gcm.AmGcmListenerService na na swoją klasę która wywoła zamiast PushActionExecutor jego rozszerzeniem z nadpisaną metodą richPushNotification()

Beacon

Beacony na systemie Android działają od systemu Android Lollipop, gdy został wspierany Bluetooth LE. Jest wymagane by do AndroidManifest.xml dodać uprawnienia aplikacji do Bluetooth:

<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

W miejscu rozpoczęcia wyszukiwania Beaconów należy zainicjalizować bibliotekę APPmanago do zarządzania beaconami

amBeaconMonitor = AmBeaconMonitor.initLibrary(getApplicationContext());

następnie sprawdzić czy:

– wersja Androida jest wyższa bądź równa Lollipop
– Bluetooth jest dostępny w urządzeniu i jest włączony

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
   mBluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
   if(mBluetoothAdapter != null && mBluetoothAdapter.isEnabled()) {
       mBluetoothLeScanner = mBluetoothAdapter.getBluetoothLeScanner();
       mBluetoothLeScanner.startScan(
               amBeaconMonitor.getScanFilter(BEACON_UUID),
               amBeaconMonitor.getScanSettings(), 
               amBeaconMonitor.getScanCallback());
   }
}

Aby przestać wyszukiwać Beacony:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
   mBluetoothLeScanner.stopScan(amBeaconMonitor.getScanCallback());
}

Metody wykorzystywane do monitorowania zachowań

amMonitor.eventStarted(NAZWA_MODUŁU, amProperties);

należy wywołać podczas uruchomienia modułu / (Activity) wraz z simpleId z systemu APPmanago. Zwykle będzie ona wołana w metodzie onResume(), w której zacznie liczyć czas spędzony w danym module.

amMonitor.eventEnded(NAZWA_MODUŁU, amProperties);

należy wykonać podczas zakończenia wykonania modułu (Activity). Zwykle będzie ona wywołana w metodzie onPause(), w której skończy liczyć czas spędzony w module.

amMonitor.eventCustom(NAZWA_CUSTOM_EVENT, amProperties);

należy wykonać podczas przesyłania zdarzeń zewnętrznych. Zdarzenia te powinny być zdefiniowane również w systemie APPmanago.

amMonitor.clicked(NAZWA_FUNKCJI, amProperties);

należy wykorzystać podczas uruchamiania metod, które są zmapowane na platformie APPmanago. Jego użycie będzie zliczało ilość metod wykonanych dla danego użytkownika.

amMonitor.syncEmail(ADRES_EMAIL);

należy wykorzystać w momencie, gdy użytkownik przekazuje swój adres email. Będzie on używany jako identyfikator danego użytkownika w APPmanago.

amMonitor.syncMsisdn(NUMER_TELEFONU);

należy wykorzystać w momencie, gdy użytkownik przekazuje swój numer telefonu.

amMonitor.sendUserProperties(MAPA_WŁAŚCIWOŚCI);

przekazuje do APPmanago dane o użytkowniku. Jest to mapa klucz-wartość, w której można przechowywać dodatkowe informacje o użytkowniku takie jak imię, nazwisko, rozmiar buta, itp. Dane te są wykorzystywane do wysyłania personalnych powiadomień i ustawień dynamicznych segmentów.

amMonitor.sendLocation(SZEROKOŚĆ, DŁUGOŚĆ);

służy do przesyłania lokalizacji

AmExtras amExtras = amMonitor.getAmExtras(bundle)
amExtras.getPayload();
amExtras.getPushType();

pozwalają odczytać payload z powiadomienia oraz jego typ. Dzięki niemu można m.in. dodać akcję, przekierować użytkownika w aplikacji, bądź wyświetlić coś jako akcję po kliknięciu w powiadomienie.