Appoxee Android SDK Integration

Step 1 - Enable Push Notifications for your application

Follow the instructions in Appoxee's Android Push Notifications Guide.

Step 2 - Download the Appoxee Android SDK

Go to the Android SDK Downloads page, download the Appoxee Android SDK and extract it to the designated Eclipse folder.

1. Choose your Eclipse workspace.
2. Create a new Eclipse folder from an existing project.
3. On the top menu choose "file" > "New" > "Other."

4. Select the "Android Project From Existing Code" option

1. 
2. 
   5
   .Choose the Appoxee resources project and click "Finish".

Step 3 - Include the Appoxee Resources

1. Choose your Application Project and click "Properties".
   
   
   

2. Include the Appoxee Project as a dependency to your project. In the Android menu click the "Add" button and choose the Appoxee Resources Project.
   
   
   

   NOTE

   Make sure that the file android-support-v4.jar is used only once inside your project. If you have a duplication error, remove the duplication from Appoxee Resources libs if exists.

Step 4 - Integration

This section uses the following typographic conventions:

• Regular text = existing code you should already have in your project by default.
• Bold text = new code you should copy & paste / add to your application.
• Green text = comments about the function, what it does and what you can do with it including special notices. We recommend you read them thoroughly as well.
• Blue text - comments within XML files (i.e. AndroidManifest.xml)

1. Create a new Class which extends com.appoxee.Configuration:
   public class AppoxeeConfiguration extends com.appoxee.Configuration 
   {
   

   public AppoxeeConfiguration()
   {
   

   //the sdk key and secret key can be found in your Appoxee application setting
   //"Application Appoxee SDK Key" from your Application Settings 
   SetAppSDKKey("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
   //"Application Appoxee Secret Key" from your Application Settings 
   SetAppSecretKey("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
   //If your app have an inbox, use true, if not, use false 
   SetAppoxeeInboxEnable(true);
   //This is the activity which will be launched after your receive push notification or after the inbox is closed.
   SetAppDefaultActivityClass("com.myApp.DefaultActivity");

   }

   
   }
2. In your Application code, be sure to initialize Appoxee with the configuration you have created:
   public class MyApplication extends Application 
   {
   

   @Override
   public void onCreate()
   {
   

   super.onCreate();
   Appoxee.Setup(this, new AppoxeeConfiguration());

   }

   }

   If prompted with an error, add this import command to enable Appoxee SDK usage:

   import com.appoxee.Appoxee
3. Make the following changes in the application's AndroidManifest.xml:
   1. GCM requires Android 2.2 or later, so if your application 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

      Step b is not required if you are targeting your application to android version 4.1 or above (i.e. minSdkVersion 16). Please proceed to step c.

      
      

   2. 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" />
      
      

      You need to replace com.appoxee.example with the package name of your app as defined by the manifest tag, otherwise it will not work.
       

      
      

   3. Add the following permissions to enable you application the usage of Google's Push Notification Service (i.e GCM):
      <!-- 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" />
      
      
      
   4. In the Application element (in the manifest file), make sure that you app name is the same name as your class file :
      <application android:label="@string/app_name"
      android:icon="@drawable/ic_launcher"
      android:allowClearUserData="true"
      android:enabled="true" android:name="MyApplication"/>
      
   5. Add the following child element to your Application element (don't forget to replace "com.appoxee.example" with the package name of your app 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>
      

      
      

      NOTE

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

      
      
      

   6. To enable your application's inbox and other anvanced features, add the following code inside your Application element :
      <activity android:name="com.appoxee.Inbox"/>
      <activity android:name="com.appoxee.MoreApps"/>
      <activity android:name="com.appoxee.Feedback"/>
      <activity android:name ="com.appoxee.InboxMessage"/>

    

   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 utilise its features (see Android SDK integration Instructions Step 5).

   
   

Your xml manifest should be similar to this:

1. The application needs to notify the Appoxee server when it starts/ends in order to allow the analytics functionality to work. The functions Appoxee.onStart() and Appoxee.onStop() needs to be called from the appropriate places (most likely from within your main activity):
   //Your Main Activity Code... 
   {
   ...

   @Override
   public void onResume() 
   {
   

   super.onResume();
   Appoxee.onStart();

   }

   @Override
   public void onPause() 
   {
   

   super.onPause();
   Appoxee.onStop();

   }
2. If you enabled the Appoxee Inbox feature, it can be opened from any activity. In the example code below it will be opened from the main activity layout using openInbox():
   public void openInbox(View view)

   { 
   

   Intent intent = new Intent(this, Inbox.class);
   intent.setFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
   this.startActivity(intent); 

   }
    
3. It is recommended that in the activity layout you should add a button to open the inbox:
   <Button 
   android:id="@+id/open_inbox" 
   android:layout_width="match_parent" 
   android:layout_height="wrap_content" 
   android:onClick="openInbox"
   android:text="Open Appoxee Inbox" />
4. In case you would like to show the number of unread message to the user, you can fetch them by using the following command:
   Appoxee.getUnreadMessages();

Step 5 - Push Icon Customization

To change the icon on the Android Push Notification panel:

1. In the "Appoxee resources/res/drawable" replace "appoxee_default_icon.png" with another icon file.
2. In the application project create a “drawable” resource by the name "appoxee_custom_icon.png". It will be used instead of the default one.

Step 6 - Inbox Customization

Appoxee Pro accounts can also change the Inbox design and customize its environment (this section is relevant for Appoxee Pro clients only. If you wish to upgrade to Pro please contact info@appoxee.com).

Step 7 -Try our feedback module

If you are using the Appoxee Inbox, all you have to do is enable it in your Appoxee app settings and hooray! check your inbox for our feedback module.

Step 8 - Testing your Application

After completing the steps above, try to build and run your application on your device. You can see in your debug console (LogCAT for Eclipse users) the logging process. 

Step 9 - Validate your integration

1. Test a push notification - if you have any problems, please read our Android Q&A section, it might be something common.
2. If you have utilized the Appoxee In-App inbox – Please test the combination of Message + Push.
3. Setup the push sending rate (in case you want to throttle incoming traffic when users click on your push notifications).
4. Create your first Welcome Message using “Persistent” Message Type.

Congratulations!!! You are now ready to use Appoxee!