Versions Compared

Version Old Version 1 New Version Current
Changes made by

Former user

Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

This document explains how to add the Appoxee code to your application code (step 3 of the Appoxee Android SDK integration process).

What's new in 2.0

As of V2.0, we have modified and improved the integration process to handle SDK Readiness to perform API Calls and to gather more accurate analytics.

We now have 2 options of Integration : Explicit & Implicit.

Explicit integration enables (through inheritance and interface implementation) an automated process of sending analytics data to Appoxee and to control API Calls (Tags, Alias etc.) through an Observer (Callback Methods implementation in your code which are declared in AppoxeeObserver) that will indicate if the SDK is done loading and ready to process the API Calls. This will save the trouble of checking if the SDK is ready through a separate thread or any other means.

Explicit Integration is the preferred way.

...

Info
titleUsing Google Play Services

Appoxee SDK uses Google Play Services, which is supported on devices using the Google Play store, and are running Android 2.3 and above.

For more info / troubleshooting see Google Play Services documentation: https://developers.google.com/android/guides/setup

 

The code sections below use the following typographic conventions:

  • Regular text - existing code: You should already have this code in your project by default. No changes are required.
  • Bold text - new code: Make sure you add this Appoxee code to your app code.
  • Green text - comments: A comment describes the code that follows it and notes special issues you should pay attention to. Please read the comments carefully.
  • Blue text - AndroidManifest.xml updates: The changes you should make in the app's AndroidManifest.xml file.

Integration Instructions

The integration has two parts:

  1. Source code integration - Integration into the source code which can be done in two ways:
    1. Explicit - Explicit integration enables (through inheritance and interface implementation) an automated process of sending analytics data to Appoxee and to control API Calls (Tags, Alias etc.) through an Observer (Callback Methods implementation in your code which are declared in AppoxeeObserver)  that will indicate if the SDK is done loading and ready to process the API Calls. This will save the trouble of checking if the SDK is ready through a separate thread or any other means. Explicit Integration is the preferred way.
    2. Implicit - Implicit Integration is a form of Integration that can be done if your code doesn't allow you to inherit from Appoxee and to implement it's Observer Interface. Both Integrations are explained below.
  2. Manifest Integration and Advanced Options (Inbox / DeepLink (URLScheme) ) - Needed in either case of Code Integration (Explicit/Implicit)
Eclipse Users : When compiling a production APK file with ProGuard and Appoxee
Note
Note

If you are using Eclipse and ProGuard, enter the following lines into the file "proguard-project.txt"

Code Block
languagetext
titleProGuard in Eclipse
linenumberstrue
-dontwarn

# OrmLite uses reflection

-keep class com.j256.**

-keepclassmembers class com.j256.** { *; }

-keep enum com.j256.**

-keepclassmembers enum com.j256.** { *; }

-keep interface com.j256.**

-keepclassmembers interface com.j256.** { *; }

-keepattributes Signature

-keepattributes *Annotation*

-keepclassmembers class * { public <init>(android.content.Context); }

In order to avoid these additions in each activity, you can simply extend AppoxeeBaseActivity instead of Activity. (AppoxeeBaseActivity extends Android’s FragmentActivity and contains the onStart() & onStop() calls)

 

Source code integration

Option A: Explicit Integration (with Observer) : 

...

 

...

On your main activity class  add the following code to Activity life-cycle callback methods:

Code Block
languagejava
linenumberstrue
@Override
protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
		 ...
		 new initAsync(getApplicationContext(),"APP_KEY",

...


                     "SECRET_KEY", true, "com.package.MainActivity"

...

).execute();

...


		AppoxeeManager.setDebug(true);

...

Appoxee.parseExtraFields(getIntent().getExtras());

setContentView(R.layout.main);

.....

Make sure that the following methods are implemented and contain Appoxee's method calls :

@Override

   protected void onResume()

      {

    super.onResume();

 // If Inbox implemented and you have a method for updating your inbox’s

 // Badge

      updateMsgBadge();

      }

 

d. @Override

 public void onRegistrationCompleted() {

  // TODO Auto-generated method stub

    Utils.Debug("Can perform all API Calls");

    

 }

 

 @Override

 public void onMessagesUpdateCompleted() {

           // If Inbox implemented and you have a method for updating your inbox’s

 // Badge

 

      Utils.Debug("Can update Badge");

      updateMsgBadge();

 

 }

...

To fully use Appoxee’s Analytics , all of your activities should implement onStart() & onStop in the actvities code :

 

@Override

protected void onStart()

              {

...

	//set 'false' to get less debug logs 	
		...
}
 
@Override  
protected void onStart() {
	super.onStart();

...


	Appoxee.onStart();

...

             }

   

@Override

             protected void onStop()

             {

...


	...
}

@Override
protected void onStop() {
	Appoxee.onStop();

...

	
	super.onStop();

...


	...
}

 

In order to avoid these additions in each activity, you can simply extend AppoxeeBaseActivity instead of Activity. (AppoxeeBaseActivity extends Android’s FragmentActivity and contains the onStart() & onStop() calls)

Option B: Implicit Integration (without using Observer)

In your main activity class onCreate() method enter the following code :

new initAsync(getApplicationContext(),"APP_KEY",

                     "SECRET_KEY", true, "com.package.MainActivity").execute();

AppoxeeManager.setDebug(true);

Appoxee.parseExtraFields(getIntent().getExtras());

setContentView(R.layout.main);

.....

...

 

...

  {

...

  super.onStart();

...

  Appoxee.onStart();

...

  }

...

 @Override

...

  protected void onStop()

...

  {

...

  super.onStop();

...

  Appoxee.onStop();

...

  }

...

     protected void onNewIntent(Intent intent)

...

     {

...

         super.onNewIntent(intent);

...

         Bundle bundle = intent.getExtras();

...

         Appoxee.parseExtraFields(bundle);

}

@Override 

protected void onResume()

...

 {

  super.onResume();

...

 // If Inbox implemented and you have a method for updating your inbox’s

...

 // Badge

...

  updateMsgBadge();

...

 }

...

You may want to add observer to Appoxee callbacks.

To do so, you'll have to implement the AppoxeeObserver interface and implement callbacks.

Example:

Code Block
public class AppoxeeExampleActivity extends Activity implements AppoxeeObserver{
	
	...
 
	@Override
	public void onRegistrationCompleted() {
		//from this point on, Appoxee API is avaliable
	}

	@Override
	public void onMessagesUpdateCompleted() {
		//callback for getting inbox messages
	}

	@Override
	public void onRegistrationFailure() {
		//Huston, we have a problem... 
	}

	@Override
	public void onGeoRegistrationFailure() {
		//This is for future support ;)
	}
 
	...

}

 

 

Note

All Appoxee API calls will fail until Appoxee has finished initialization. When Integrating Appoxee and choosing not to use an Observer

...

(and sometimes when do), you may consider checking if

Code Block
Appoxee.isReady() == true

...

before doing such operations.


Note

To fully use Appoxee’s Analytics , all of your activities should implement onStart() & onStop in the actvities code :

...

 

@Override

...

Code Block
languagejava
linenumberstrue
@Override  
protected void onStart()

...

              {

...

 {
	super.onStart();

...


	Appoxee.onStart();

...

             }

   

@Override

             protected void onStop()

             {

...


	...
}

@Override
protected void onStop() {
	Appoxee.onStop();

...

	
	super.onStop();

...

             }

 

In order to avoid these additions in each activity, you can simply extend AppoxeeBaseActivity instead of Activity. (AppoxeeBaseActivity extends Android’s FragmentActivity and contains the onStart() & onStop() calls)

 

...


	...
}

 

Advanced Options (Inbox / DeepLink (URLScheme) ) :

  1. If prompted with an error, add this "Import" command to enable Appoxee SDK usage:

    import com.appoxee.Appoxee
    AndroidManifest.xml Updates - Make the following changes to your app's AndroidManifest.xml file:

  2. GCM requires Android 2.2 or later. If your app cannot work without GCM, add the following line, where "xx" is the latest target SDK version:

    <uses-sdk android:minSdkVersion="8" android:targetSdkVersion="xx" /> 
    Note
    If your application is intended for android version 4.1 or above (that is, minSdkVersion 16), the next step (2.b.) is not required.
    In this case, please skip the next step and proceed to step 2.c.

  3. Declare and use a custom permission, so only this application can receive GCM messages:

    <permission android:name="com.appoxee.example.permission.C2D_MESSAGE" android:protectionLevel="signature" /> 
    <uses-permission android:name="com.appoxee.example.permission.C2D_MESSAGE" />
    Note

    You must replace "com.appoxee.example" with your app's package name, as defined by the manifest tag, otherwise it will not work.

  4. To allow your app to use Google's Push Notification Service (GCM), add the following permissions: 

    <!-- This app has permission to register and receive message -->
    <!-- App receives GCM messages. -->
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /> 
    <!-- GCM connects to Google Services. -->
    <uses-permission android:name="android.permission.INTERNET" /> 
    <!-- GCM requires a Google account. -->
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <!-- Keeps the processor from sleeping when a message is received. -->
    <uses-permission android:name="android.permission.WAKE_LOCK" />

     

    5. In the manifest file's Application element, make sure your app has the name it has in your class file:

    <application android:label="@string/app_name"
    android:icon="@drawable/ic_launcher"
    android:allowClearUserData="true"
    android:enabled="true" android:name="MyApplication"/>
    The class that extends "Application" that is the name that needs to be in the "MyApplication".Example:
    If the package name is "com.david.coolapps" and the class that extends Application is named "MyApp"
    then in the Application tag the "name" value is : "com.david.coolapps.MyApp" . 
    <application
    android:name="com.david.coolapps.MyApp"
    ..... >

     

  5.  Add the following child element to your Application element (remember you must replace "com.appoxee.example" with your app's package name, as defined by the manifest tag):

    <service android:name="com.appoxee.gcm.GCMIntentService"/>
    <receiver android:name="com.appoxee.gcm.GCMBroadcastReceiver"
    android:permission="com.google.android.c2dm.permission.SEND">
    <!-- Receive the actual message -->
    <intent-filter>
    <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    <category android:name="com.appoxee.example" />
    </intent-filter>
    <!-- Receive the registration id -->
    <intent-filter>
    <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
    <category android:name="com.appoxee.example" />
    </intent-filter>
    </receiver> <!-- Must have for Push Support by Appoxee --> <activity android:name ="com.appoxee.InboxMessage"/>
    Note

    If you are using Appoxee's SDK as a "Push Only" solution (without using the Inbox that enables Rich Messages), this completes the integration procedure within the AndroidManifest.xml file.
    Please continue to step 5 to complete the rest of the integration by adding your java code

    6. To enable Appoxee's in-app inbox, and other advanced features, add the following code inside your Application element:

    <activity android:name="com.appoxee.activities.Inbox"/>
    <activity android:name="com.appoxee.activities.MoreApps"/>
    <activity android:name="com.appoxee.activities.Feedback"/> <!-- Add if missing from Push Integration -->
    <activity android:name ="com.appoxee.activities.InboxMessage"/>
    Code Block
    languagejava
    linenumberstrue
    import com.appoxee.Appoxee;

  6. Inbox integration - after enabling the Inbox in your Appoxee account (by going to the app's Application Information page and checking Allow Inbox + Rich messages), add the Inbox to your code as follows: 

     

    Note

    The Inbox feature guarantees your ability to engage the user with rich messages (note that the Inbox cannot be disabled by users, as opposed to Push Notifications) and gives you the option to access features such as Feedback and More Apps . The Inbox must be used in your application's code in order to show it and utilize its features. The InboxMessage activity needs to be added in order to support Push Notifications by Appoxee. Check your Manifest.xml and see that it is added below the Receiver declaration.

    Your updated AndroidManifest.xml file should be similar to the following example XML: <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.demo"
    android:versionCode="1"
    android:versionName="1.0" > 
    <uses-sdk android:minSdkVersion="8" /> 
    <!-- REQUIRED -->
    <uses-permission android:name="android.permission.INTERNET" /> 
    <uses-permission android:name="android.permission.VIBRATE" /> 
    <!-- REQUIRED for GCM -->
    <!-- Only this application can receive the messages and registration result -->
    <permission android:name="com.appoxee.example.permission.C2D_MESSAGE"android:protectionLevel="signature" /> 
    <uses-permission android:name="com.appoxee.example.permission.C2D_MESSAGE" />
    <!-- This app has permission to register and receive message -->
    <!-- App receives GCM messages. -->
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /> 
    <!-- GCM connects to Google Services. -->
    <uses-permission android:name="android.permission.INTERNET" />

     

    <!-- GCM requires a Google account. -->
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <!-- Keeps the processor from sleeping when a message is received. -->
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <!—The name of MyApplication Needs to be replaced with the name of the class of your application -->
    <application android:label="@string/app_name"
    android:icon="@drawable/ic_launcher"
    android:allowClearUserData="true"
    android:enabled="true" android:name="MyApplication"/>
    <activity android:name="DemoActivity" android:label="@string/app_name"/>
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <!-- REQUIRED for GCM -->
    <service android:name="com.appoxee.gcm.GCMIntentService"/>
    <receiver android:name="com.appoxee.gcm.GCMBroadcastReceiver"
    android:permission="com.google.android.c2dm.permission.SEND">
    <!-- Receive the actual message -->
    <intent-filter>
    <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    <category android:name="com.appoxee.example" />
    </intent-filter>
    <!-- Receive the registration id -->
    <intent-filter>
    <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
    <category android:name="com.appoxee.example" />
    </intent-filter>
    </receiver>
    <!-- Add the following intents to your application if Inbox and other advanced features are enabled -->
    <activity android:name="com.appoxee.activities.Inbox"/>
    <activity android:name="com.appoxee.activities.MoreApps"/>
    <activity android:name="com.appoxee.activities.Feedback"/>
    <activity android:name ="com.appoxee.activities.InboxMessage"/></application>
    </manifest> 

     This completes the AndroidManifest.xml file updates. The remaining updates are made in your app code.
     

    Inbox integration - after enabling the Inbox in your Appoxee account (by going to the app's Application Information page and checking Allow Inbox + Rich messages), add the Inbox to your code as follows: 

    1. Add code that opens the Inbox - the Inbox can be opened from any activity. In the example code below, the Inbox is opened from the main activity layout, using the "openInbox():" function:

      Code Block
      languagejava
      linenumberstrue
      public void openInbox(View view)
      { 
       Intent intent = new 
       { 
 Intent intent = new Intent(this, Inbox.class);

      
 intent.setFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);

      
 this.startActivity(intent);
      
}

    2. Add a button that opens the Inbox - it is recommended to add a button to open the Inbox. This button is added in the activity layout as follows:

      <Button 

      Code Block
      languagexml
      linenumberstrue
      <Button 
android:id="@+id/open_inbox"
       
       
android:layout_width="match_parent"
       
       
android:layout_height="wrap_content"
       
       
android:onClick="openInbox"

      
android:text="Open
       Appoxee 
       Appoxee Inbox" />

    3. Show the number of unread messages - to show the user the number of unread messages, fetch this number using the following command:

      Code Block
      languagejava
      linenumberstrue
      Appoxee.getUnreadMessages();

       

       

       

  7. Depp Deep Link / URL Scheme in Appoxee & Android

    1. Add to your AndroidManifest.xml

      <activity 
      Code Block
      languagexml
      linenumberstrue
      <activity android:name="com.appoxee.example.DeepLinkActivity"
       >

       

                  
       >
   <!-- Add the Intent Filter for activity needed to be URLScheme compatible -->

                  <intent-filter>

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

       

       

          </activity>

    2. Create DeepLinkActivity.java

      Code Block
      languagejava
      titleDeepLink Activity Sample
      linenumberstrue
      //This sample extends AppoxeeBaseActivity, for onStart() & onStop() integration and analytics

      
public class DeepLinkActivity extends AppoxeeBaseActivity
      {

       

       @Override

        public void 
       {

 @Override
  public void onCreate(Bundle savedInstanceState)
      {          
       {
      super.onCreate(savedInstanceState);

       

                Intent intent = 
      
      Intent intent = getIntent();
                if (intent == null || 
      
      if (intent == null || intent.getData() == null)
      {

                    finish();

                }

       

                
       {
              finish();
      }

      openDeepLink(intent.getData());

       

                // Finish this activity

                finish();

            }

         

         public void openDeepLink(Uri deepLink) {

                String path = 
      

      // Finish this activity
      finish();
   }
   
   public void openDeepLink(Uri deepLink) {
    String path = deepLink.getPath();
          
      
    Utils.Debug("Base path: " + path);
       
      
    //Implement your Code
      here    path = 
       here
    path = path.replace("/", "");

       

          Intent intent = new 
      


    Intent intent = new Intent();
          
      
    intent.setClassName(this, path);
                
      
    this.startActivity(intent);

                

         } 
            
   } .....

...

    1.

You are now done integrating the Appoxee SDK! Congrats!

1. If you wish to use the SDK Sync API's - press here

2. If you wish to use the SDK Async API's - press here 

3. If you wish to use the Custom Push Notification Builder - press here

As mentioned earlier, our Test Application contains a full code sample. it can be downloaded from here.