Introduction

Welcome to the Popdeem Android SDK Documentation

Integrate Popdeem into your mobile app today! Our integration is simple and fast - you can be up and running in under 30 minutes. If you are new - Request a Demo to see what we can do.

Getting Started

Dependency

The Popdeem Android SDK is available through jcenter and mavenCentral.

In your top-level build.gradle file add the lines marked in the sample below:

Top level build.gradle

allprojects {
    repositories {
        google()
        jcenter()
        maven { url "https://jitpack.io" } // Add this line
    }
}

Add the following between the buildscripts and the allprojects:

ext {
    compileSdkVersion = 28
    supportLibVersion = "28.0.0"
}

implementation "com.android.support:appcompat-v7:${rootProject.ext.supportLibVersion}"

These should be set to the same level as your project sdk version and support library. To avoid conflicts we recommend setting all support libraries using the following:

implementation 'com.popdeem.sdk:sdk:1.4.1'

Add the following line to the dependencies block of your applications build.gradle file and Gradle Sync your project to download the SDK dependency:

Initialise SDK

API Key

<meta-data
    android:name="com.popdeem.sdk.ApiKey"
    android:value="YOUR_POPDEEM_API_KEY" />

Add your Popdeem API Key to your applications AndroidManifest.xml inside the <application> tags:

Permissions

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Add the following permissions to your applications AndroidManifest.xml if they are not already declared.

Broadcast Features

To use the Popdeem Push Notification and Broadcast feature, your application must have Firebase setup. Go to Firebase and create a project for your application. Add your application details to the cloud messaging and place the google-services.json in the same folder as your app level build.gradle

classpath 'com.google.gms:google-services:4.0.1'

In the buildscripts->dependencies add the following:

apply plugin: 'com.google.gms.google-services'

At the bottom of the applications build.gradle add the following line:

Initialise Popdeem SDK

PopdeemSDK.initializeSDK(this);

To initialise the Popdeem SDK add the following line to your Application class:

For Applications that use Realm

If your application uses Realm you will need to add the Popdeem SDK's schema to your Realm Configuration. You can read about this here in the Realm documentation.

RealmConfiguration config = new RealmConfiguration.Builder(this)
        .schemaVersion(1)
        .modules(Realm.getDefaultModule(), new PDRealmModule())
        .name("yourdbname.realm")
        .build();
Realm.setDefaultConfiguration(config);

The Popdeem SDK's Realm Module class is PDRealmModule. A sample RealmConfiguration might look like this when including Popdeem's Realm Module:

Facebook Setup

You will need to set up a Facebook application at the Facebook Dev Centre. You can do so by following this Tutorial.

Popdeem SDK already includes the Facebook SDK dependency (v4.38.1) so your application will inherit this.

Strings.xml

<string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
<string name="fb_login_protocol_scheme">fbYOUR_FACEBOOK_APP_ID</string>
<string name="facebook_app_name">YOUR_FACEBOOK_APP_NAME</string>

When you have your Facebook app set up, make note of your Facebook App ID. Add the following to your Android applications string.xml file:

AndroidManifest.xml

<meta-data android:name="com.facebook.sdk.ApplicationId"
    android:value="@string/facebook_app_id"/>

<meta-data android:name="com.facebook.sdk.ApplicationName"
    android:value="@string/facebook_app_name" />

<activity android:name="com.facebook.FacebookActivity"
    android:configChanges=
        "keyboard|keyboardHidden|screenLayout|screenSize|orientation"
    android:label="@string/app_name" />

<provider android:authorities="com.facebook.app.FacebookContentProviderXXXXXXXXXXXXXX" 
    android:name="com.facebook.FacebookContentProvider"
    android:exported="true" />

<activity
    android:name="com.facebook.CustomTabActivity"
    android:exported="true">
    <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="@string/fb_login_protocol_scheme" />
    </intent-filter>
</activity>

Then in your AndroidManifest.xml file add these lines inside the <application> tags:

Note: XXXXXXXXXXXXXX in the above provider should be replaced with your Facebook app id.

Twitter Setup

If you do not have a Twitter app and the corresponding consumer secret and consumer key you can create an app here and generate the keys needed to continue.

Once you have the Twitter app consumer key and consumer secret add the following lines to your AndroidMainfest.xml inside the <application> tags:

AndroidManifest.xml

<meta-data
    android:name="TwitterConsumerKey"
    android:value="YOUR_TWITTER_CONSUMER_KEY" />

<meta-data
    android:name="TwitterConsumerSecret"
    android:value="YOUR_TWITTER_CONSUMER_SECRET" />

Instagram Setup

If you do not have an Instagram app and the corresponding Client ID and Secret you can create one here and generate the keys needed to continue.

Once you have the Client ID and Secret for your Instagram app, add the following lines to your AndroidManifest.xml inside the <application> tags:

AndroidManifest.xml

<meta-data
    android:name="InstagramClientId"
    android:value="YOUR_INSTAGRAM_CLIENT_ID" />

<meta-data
    android:name="InstagramClientSecret"
    android:value="YOUR_INSTAGRAM_CLIENT_SECRET" />

<meta-data
    android:name="InstagramCallbackUrl"
    android:value="YOUR_INSTAGRAM_CLIENT_CALLBACK_URL" />

Social Login Flow

PopdeemSDK.enableSocialMultiLogin(MainActivity.class, 3);

To trigger the Popdeem login flow, call the enableSocialMultiLogin(@NonNull Class activityClass, int numberOfPrompts) method of the PopdeemSDK class:

The activityClass parameter denotes the Activity class that you would like the login flow to appear in. In the example above we want the login flow to appear in the applications MainActivity so we pass MainActivity.class in method.

The numberOfPrompts parameter denotes how many times you wish to ask the user to log in if they have dismissed the login pop-up.

@Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        if (requestCode == TwitterAuthConfig.DEFAULT_AUTH_REQUEST_CODE) {
            Fragment fragment = getSupportFragmentManager().findFragmentByTag("PDUISocialMultiLoginFragment");
            if (fragment != null) {
                fragment.onActivityResult(requestCode, resultCode, data);
            }
        }
    }

In the Activity class that you would like the multi login flow to appear, you must also override the Activity's onActivityResult(int requestCode, int resultCode, Intent data). This is to allow the necessary callbacks for Twitter Login to work. Below is an example of how this should look, and can also be found in the MainActivity.java of the NavigationSample.

Provided all of the items in the previous steps have been performed correctly, this login flow will result in the user being logged in.

On app launch, if the user has been previously logged in, the Popdeem SDK will take care of automatic login.

Non-Social Users

When you initialize the Popdeem SDK, a non-social user is created and registered on Popdeem. This allows you to track which of your app users have converted to Social.

Social Home

All of Popdeem's core mobile features are contained in the Home flow. There are various scenarios in which you may launch the Home flow.

Activity Implementation

From an Activity

PopdeemSDK.showHomeFlow(this);

From a Fragment

PopdeemSDK.showHomeFlow(getActivity());

The recommended way to present the Home flow is to use the standalone activity provided in the Popdeem SDK. To start this activity use one of the following lines of code depending on the type of class the call will be invoked from:

Note: An example of this can be seen in the navigationsample module in the MainActivity class.

Fragment Implementation

PDUIHomeFlowFragment.newInstance();

If you wanted to present the Home flow as a fragment instead, for example as a Tab in a TabLayout ViewPager, create an instance of the PDUIHomeFlowFragment Fragment class using the following:

This can be used in your PagerAdapter or in a FragmentTransaction depending on your requirements.

Note: An example of this can be seen in the tabbedsample module in the MainActivity class.

Deliver Third Party Token

PopdeemSDK.setThirdPartyToken("third_party_token");

We may need you to deliver a user token. If so, you can do this by using this method:

Custom Event Trigger

PopdeemSDK.logMoment("post_payment", callback);

We have created the ability for the your app to inform the Popdeem platform when certain events have occurred. We have identified post payment as a significant event in which Popdeem can take some action. The action taken can be configured on the Popdeem Platform and is flexible. Directly after a user has made a payment or completed a transaction in the your app, you should execute the following code:

The callback parameter here is a PDAPICallback instance. It has two implemented methods success() and failure() to tell you if the moment has been logged successfully.

Theme

Images

There are a few images that you can override to suit your application.

Notification Icon

To customize the notification icon that is shown when your app receives a push notification from Popdeem add an image to your drawable folders with this name: ic_pd_notification.png

We recommend using the built in Image Asset creator in Android Studio to do this as it will add an image for all densities.
To do this use File -> New -> Image Asset and choose "Notification Icons"

Home Flow Header Image

To customize the header / banner image shown in the Home Flow, add an image to your drawable folders called: pd_header_image.png

arrays.xml

<resources>
<!-- Login Images -->
<string-array name="pd_login_images">
    <item>@drawable/pd_social_login_image_1</item>
    <item>@drawable/pd_social_login_image_2</item>
    <item>@drawable/pd_social_login_image_3</item>
</string-array>

<!-- Gratitude Images -->
<string-array name="pd_coupon_images">
    <item>@drawable/pd_gratitude_coupon_image_1</item>
    <item>@drawable/pd_gratitude_coupon_image_1</item>
    <item>@drawable/pd_gratitude_coupon_image_1</item>
</string-array>

<string-array name="pd_connect_images">
    <item>@drawable/pd_gratitude_coupon_image_1</item>
    <item>@drawable/pd_gratitude_coupon_image_1</item>
    <item>@drawable/pd_gratitude_coupon_image_1</item>
</string-array>

<string-array name="pd_credit_images">
    <item>@drawable/pd_gratitude_coupon_image_1</item>
    <item>@drawable/pd_gratitude_coupon_image_1</item>
    <item>@drawable/pd_gratitude_coupon_image_1</item>
</string-array>

<string-array name="pd_sweepstake_images">
    <item>@drawable/pd_gratitude_coupon_image_1</item>
    <item>@drawable/pd_gratitude_coupon_image_1</item>
    <item>@drawable/pd_gratitude_coupon_image_1</item>
</string-array>
</resources>

Image Customisation

To customize the images shown in the app add the images to your drawable folders and add the following to the array.xml:

Colors

colors.xml

<resources>
    <color name="pd_social_login_back_button_color">#0000f4</color>
    <color name="pd_toolbar_color">#000054</color>
    <color name="pd_toolbar_text_color">#ffffff </color>
    <color name="pd_toolbar_color_dark">#31241C</color>
    <color name="pd_accent">#ffffff </color>
    <color name="pd_tab_selected_text_color">#000054</color>
    <color name="pd_tab_unselected_text_color">#000054</color>
    <color name="pd_home_flow_banner_text_color">#ffffff</color>
    <color name="pd_tab_background_color">#ffffff</color>
    <color name="pd_tab_indicator_color">#000054</color>


    <color name="primaryAppColor">#000054</color>
    <color name="secondaryAppColor">#000054</color>
    <color name="primaryInverseColor">#FFFFFF</color>
    <color name="viewBackgroundColor">#e9e9e9</color>
    <color name="primaryFontColor">#000000</color>
    <color name="secondaryFontColor">#656565</color>
    <color name="tableViewCellBackgroundColor">#FFFFFF</color>
    <color name="navBarTintColor">#000054</color>
    <color name="segmentedControlBackgroundColor">#FFFFFF</color>
    <color name="segmentedControlForegroundColor">#000054</color>
    <color name="homeHeaderTextColor">#FFFFFF</color>
</resources>

You can customize the Popdeem SDK's UI colors to help with integration. All you need to do it declare the color in your applications colors.xml file.

The colors must be named the same as they appear below

The list of colors that can be changed are as follows:

Strings

strings.xml

    <string name="pd_home_banner_text">Share your #Popdeem experience on social networks to earn more rewards.</string>
    <string name="pd_home_title">Social</string>

    <string name="login_title_1">Thanks for connecting.</string>
    <string name="login_title_2">You\'re in!</string>
    <string name="login_title_3">Success!</string>

    <string-array name="pd_gratuity_strings_login_title">
        <item>@string/login_title_1</item>
        <item>@string/login_title_2</item>
        <item>@string/login_title_3</item>
    </string-array>

    <string name="login_body_1">You can now earn additional rewards when you share your #Popdeem experience</string>
    <string name="login_body_2">Share your #Popdeem experience to earn additional rewards.</string>
    <string name="login_body_3">You can now earn additional rewards and prizes when you share your #Popdeem moments on social media.</string>

    <string-array name="pd_gratuity_strings_login_body">
        <item>@string/login_body_1</item>
        <item>@string/login_body_2</item>
        <item>@string/login_body_3</item>
    </string-array>

    <string name="grat_coupon_title_1">You are brilliant!</string>
    <string name="grat_coupon_title_2">Thanks for sharing!</string>
    <string name="grat_coupon_title_3">Amazing!</string>

    <string-array name="pd_gratuity_strings_share_coupon_title">
        <item>@string/grat_coupon_title_1</item>
        <item>@string/grat_coupon_title_2</item>
        <item>@string/grat_coupon_title_3</item>
    </string-array>

    <string name="grat_coupon_body_1">Thanks for sharing. Your reward has been added to your profile.</string>
    <string name="grat_coupon_body_2">Your reward has been added to your profile</string>
    <string name="grat_coupon_body_3">Thanks for sharing your Popdeem moment. Your reward has been added to your profile.</string>


    <string-array name="pd_gratuity_strings_share_coupon_body">
        <item>@string/grat_coupon_body_1</item>
        <item>@string/grat_coupon_body_2</item>
        <item>@string/grat_coupon_body_3</item>
    </string-array>

    <string name="grat_credit_title_1">You are brilliant!</string>
    <string name="grat_credit_title_2">Thanks for sharing</string>
    <string name="grat_credit_title_3">Amazing!</string>

    <string-array name="pd_gratuity_strings_share_credit_title">
        <item>@string/grat_credit_title_1</item>
        <item>@string/grat_credit_title_2</item>
        <item>@string/grat_credit_title_3</item>
    </string-array>

    <string name="grat_credit_body_1">Thanks for sharing. %s has been added to your account.</string>
    <string name="grat_credit_body_2">%s has been added to your account</string>
    <string name="grat_credit_body_3">Thanks for sharing your Popdeem moment. %s has been added to your account</string>

    <string-array name="pd_gratuity_strings_share_credit_body">
        <item>@string/grat_credit_body_1</item>
        <item>@string/grat_credit_body_2</item>
        <item>@string/grat_credit_body_3</item>
    </string-array>

    <string name="grat_sweepstake_title_1">Thanks for sharing!</string>
    <string name="grat_sweepstake_title_2">You are in!</string>
    <string name="grat_sweepstake_title_3">Great stuff.</string>

    <string-array name="pd_gratuity_strings_share_sweepstake_title">
        <item>@string/grat_sweepstake_title_1</item>
        <item>@string/grat_sweepstake_title_2</item>
        <item>@string/grat_sweepstake_title_3</item>
    </string-array>

    <string name="grat_sweepstake_body_1">You have successfully entered the competition, check your profile to know when the winner is announced.</string>
    <string name="grat_sweepstake_body_2">You have been entered into the competition, we will let you know if you are the winner.</string>
    <string name="grat_sweepstake_body_3">Check your profile to find out when the winner is announced.</string>

    <string-array name="pd_gratuity_strings_share_sweepstake_body">
        <item>@string/grat_sweepstake_body_1</item>
        <item>@string/grat_sweepstake_body_2</item>
        <item>@string/grat_sweepstake_body_3</item>
    </string-array>


    <string name="sociallogin_title_1">New: Social Rewards.</string>
    <string name="sociallogin_title_2">New: Social Rewards.</string>
    <string name="sociallogin_title_3">New: Social Rewards.</string>

    <string-array name="pd_sociallogin_title">
        <item>@string/sociallogin_title_1</item>
        <item>@string/sociallogin_title_2</item>
        <item>@string/sociallogin_title_3</item>
    </string-array>

    <string name="sociallogin_body_1">Connect with Popdeem on social media to earn additional rewards!</string>
    <string name="sociallogin_body_2">Connect with Popdeem on social media to earn additional rewards!</string>
    <string name="sociallogin_body_3">Connect with Popdeem on social media to earn additional rewards!</string>

    <string-array name="pd_sociallogin_body">
        <item>@string/sociallogin_body_1</item>
        <item>@string/sociallogin_body_2</item>
        <item>@string/sociallogin_body_3</item>
    </string-array>

All of the strings in the PopdeemSDK integration are translatable using the strings.xml file. To override any strings in the SDK, simply add the corresponding string to your strings.xml.

The strings must be named the same as they appear below

If you need to translate the Popdeem SDK you can request a full list of the strings from daniel.f@popdeem.com