Audience Insight & Offers SDK

Developer Guide

  • Follow this easy-to-use guide to integrate our SDK into your mobile application. Once updated, you will start gathering valuable user insight and be able to push offers to users based on their exact location.

  • Import the SDK

    Open your app's project-level
    build.gradle
    file and look for an
    allprojects
    section and add JitPack:
    
      allprojects {
        repositories {
          google()
          jcenter()
          maven { url 'https://jitpack.io' } //add this line
        }
      }
    
    Add the following line to the
    dependencies{}
    element in your app module’s build.gradle file:
    
      implementation ‘org.bitbucket.geo-offers:geo-offers:1.2.4’
    
    
  • Dependencies

    Add the following lines to the
    dependencies{}
    element in your app module’s build.gradle file, where they don’t already exist:
    
      implementation 'com.google.android.gms:play-services-gcm:16.0.0'
      implementation 'com.google.firebase:firebase-core:16.0.4'
      implementation 'com.firebase:firebase-jobdispatcher:0.8.5'
      implementation 'com.android.support.constraint:constraint-layout:1.1.3'
      implementation 'com.google.code.gson:gson:2.8.5'
      implementation 'com.google.android.gms:play-services-location:16.0.0'
      implementation 'com.google.firebase:firebase-messaging:17.3.4'
    
    
    The following permissions are added for you automatically (you don’t need to add them in your own AndroidManifest.xml):
    
      android.permission.FOREGROUND_SERVICE
      android.permission.ACCESS_COARSE_LOCATION
      android.permission.ACCESS_FINE_LOCATION
      android.permission.INTERNET
      android.permission.ACCESS_WIFI_STATE
      android.permission.ACCESS_NETWORK_STATE
      android.permission.RECEIVE_BOOT_COMPLETED
    
  • Access Keys

    Place the following code in the
    <resources>
    element of any xml file in your res/values folder:
    
      <string name="geoOffersAccountCode">XXXXXX</string>
      <string name="geoOffersApiKey">XXXX-XXXX-XXXX-XXXX</string>
    
    
    Replace
    XXXXXX
    with your 6 digit account code, available from within your geo-offers account, and
    XXXX-XXXX-XXXX-XXXX
    with your API key, which we provide upon request.
  • Customise settings

    Place the following code in the
    <resources>
    element of any xml file in your res/values folder:
    
      <drawable name="geoOffersNotificationsSmallIcon">@drawable/app_icon</drawable>
      <color name="geoOffersActiveTabColor">#XXXXXX</color>
      <color name="geoOffersNotificationAccentColor">#XXXXXX</color>
    
    Replace
    @drawable/app_icon
    with a reference to the small icon you want displayed with Geo-Offers notifications. Set the background colour of the offers view active tab using
    geoOffersActiveTabColor
    . Set the icon and app name title colour in the notifications menu using
    geoOffersNotificationAccentColor
    .
  • Initialise Library

    Use the following code in the main launcher activity of your application. Keep a reference to the
    GeoOffersNotifications
    in your activity as follows:
    
        //As an instance member of your activity class:
        GeoOffersNotifications geoOffersNotifications;
    
    Add the following code in your Activity's
    onCreate
    method:
    
        geoOffersNotifications =
          GeoOffersNotifications
            .startIfNotAlready(
              this,
              //where “this” is a reference to this activity
    
              new GeoOffersOptions()
                .setNotificationsTargetActivityClass(
                  MyOffersActivity.class
                  //Replace “MyOffersActivity” with the class name of the activity
                  //you want to be launched when a user taps a offers
                  //notification. It should be an activity
                  //which shows a GeoOffersView upon launch
                )
            )
        ;
    
    then add the following code to the activity class, adding the relevant lines where you have already overridden these methods:
    
      @Override
      public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
          //add this line if you have already overridden onRequestPermissionsResult:
          geoOffersNotifications.onRequestPermissionsResult(requestCode, permissions, grantResults);
      }
    
      @Override
      protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    	   //add this line if you have already overridden onActivityResult:
    	   geoOffersNotifications.onActivityResult(requestCode, resultCode, data);
      }
    
  • Toggle notifications (optional)

    Allow users to turn notifications on/off via the following method e.g. in a toggle button handler:
    
      GeoOffersNotifications
        .setAllowOffersNotifications(
          context,
          true //or false
        )
      ;
    
    Check the status of this value using the following method:
    
      GeoOffersNotifications
        .isAllowingOffersNotifications(
          context
        )
      ;
    
  • Display offers

    To insert the offers view into your own activity or fragment, use the following code in your activity or fragment’s layout XML:
    
      <com.geooffers.GeoOffersView
          android:id="@+id/geoOffersView"
          android:layout_width="match_parent"
          android:layout_height="match_parent"
          />
    
    Then replace the
    layout_width
    and
    layout_height
    parameter values with your own preferred values instead of
    match_parent
    if different.
    GeoOffersView
    has all the same layout parameter options as a
    FrameLayout
    . In your activity class, which hosts the
    GeoOffersView
    , there should be a reference to the
    GeoOffersView
    as follows:
    
      GeoOffersView geoOffersView;
    
    Call the following code to activate the
    GeoOffersView
    . Call this only once, e.g. in your Activity’s
    onCreate
    method:
    
      geoOffersView = findViewById(R.id.geoOffersView);
      geoOffersView.start(this);
    
    (Optional) To listen for various events in the offers view, use any combination of the following callbacks. Insert the below code immediately after
    geoOffersView.start(this)
    :
    
      geoOffersView
        .setOffersLoadingStartedHandler(
          new OffersLoadingStartedHandler() {
            @Override
            public void handleOffersLoadingStarted() {
              //handle (optional)
            }
          }
        )
        .setOffersLoadingCompletedHandler(
          new OffersLoadingCompletedHandler() {
            @Override
            public void handleOffersLoadingCompleted() {
              //handle (optional)
            }
          }
        )
        .setNoCollectedOffersLoadedHandler(
          new NoCollectedOffersLoadedHandler() {
            @Override
            public void handleNoCollectedOffersLoaded() {
              //handle (optional)
            }
          }
        )
        .setIndividualOfferLoadingStartedHandler(
          new IndividualOfferLoadingStartedHandler() {
            @Override
            public void handleIndividualOfferLoadingStarted() {
              //handle (optional)
            }
          }
        )
        .setIndividualOfferLoadingCompletedHandler(
          new IndividualOfferLoadingCompletedHandler() {
            @Override
            public void handleIndividualOfferLoadingCompleted() {
              //handle (optional)
            }
          }
        )
      ;
    
    Add the following code to your activity class, adding the relevant lines where you have already overridden these methods:
    
        @Override
        protected void onDestroy() {
            super.onDestroy();
            geoOffersView.onDestroy(); //Add this line if you have already overridden onDestroy
        }
    
        @Override
        protected void onPause() {
            super.onPause();
            geoOffersView.onPause();
        }
    
        @Override
        protected void onResume() {
            super.onResume();
            geoOffersView.onResume();
        }
    
        @Override
        public void onBackPressed() {
            if(!geoOffersView.onBackPressed()){
                super.onBackPressed(); //OR your existing code if you have already overridden onBackPressed
            }
        }
    
    In your button click handler that navigates the user to the offers, add the following code:
    
        geoOffersView.navigateToLatestOffers()
    
  • Offers status (optional)

    Handle the successful intialization of the offers service by listening for the broadcast Intent action
    "com.geooffers.INITIALIZATION_COMPLETED"
    . If you want to check whether or not initialization happened successfully e.g. for showing or hiding a button upon app launch, you can check the return value of
    GeoOffersNotifications.isInitializationComplete(context)
    Handle receipt of new offers by listening for the broadcast Intent action
    "com.geooffers.NEW_OFFERS_RECEIVED"
    and to get the number of new offers use
    GeoOffersNotifications.getNewOffersReceivedCount(broadcastIntent)
    , passing in the intent from
    onReceive
    . Get the total number of new available offers (i.e. that haven't been viewed) using
    GeoOffersNotifications.getTotalNewOffersAvailableCount(context)
    , passing in any context in your application.
  • Detect open by notification (optional)

    To detect if your activity has been opened by an offers notification, use the following code:
    
      this
          .getIntent()
          .getBooleanExtra(
              "com.geooffers.IS_FROM_NOTIFICATION",
              false
          ) //true if opened from a offers notification
      ;
    
  • Custom permission pages (optional)

    The SDK prompts the user to share their location and allow notifications (if the app hasn't already asked for these permissions) using default, grey pages. Choose your own prompt pages via the
    GeoOffersOptions
    object parameter as follows:
    
      geoOffersNotifications =
        GeoOffersNotifications
          .startIfNotAlready(
            this,
            new GeoOffersOptions()
              .setNotificationsTargetActivityClass(MyOffersActivity.class)
              //Add these 2 lines to your existing call
              .setShareLocationPromptActivityClass(ShareLocationOptionPage.class)
              //Replace "ShareLocationOptionPage" the class name of your own activity that says e.g. "Share location?"
              .setAllowOffersNotificationsPromptActivityClass(NotificationsOptionPage.class)
              //Replace "NotificationsOptionPage" with the class name of your own activity that says e.g. "Allow offers notifications?"
          )
      ;
    
    Call setResult in your activity when the user has chosen the corresponding option on it (e.g. YES or NO). If the user chooses to accept sharing their location, for example, in the button's click handler, do the following:
    
      setResult(Activity.RESULT_OK);
      finish(); //Closes your prompt activity
    
    If the user chooses not to share their location, do the following:
    
      setResult(Activity.RESULT_CANCELED);
      finish(); //Closes your prompt activity
    
    Notification permission should be executed in the same way. After the notification permission has been set by the user, the offers service will start. If applicable, in your notification permissions activity’s button click handlers, you can start your own activity that notifies the user of this.
  • Proguard configuration

    If you are using Proguard minification, ensure the following lines are in your configuration:
    
      -dontwarn okhttp3.internal.platform.*
      -dontwarn okio.*
      -dontwarn androidx.**
      -keep class androidx.** { *; }
      -keep interface androidx.** { *; }
    
      -keepclassmembers class com.geooffers.functions.WebViewJavaScriptInterface {
        public *;
      }
    
      -keepattributes Exceptions,InnerClasses,Signature,Deprecated,SourceFile,LineNumberTable,EnclosingMethod,*Annotation*
    
      -keepclassmembers class com.geooffers.model.** {
        <fields>;
      }
    
      -keep class com.geooffers.* {
        public *;
      }
    
      -keep class com.geooffers.activity.OptionPage {
        public protected *;
      }
    
      -keepclassmembernames class * {
        java.lang.Class class$(java.lang.String);
        java.lang.Class class$(java.lang.String, boolean);
      }
    
      -keepclassmembers enum * {
        <fields>;
          public static **[] values();
          public static ** valueOf(java.lang.String);
      }