SmartAlerts (Push Notifications)¶

Welcome to The Loop

The Loop is a viral loop in your app that puts your users to work boosting downloads and re-engagement in your app.

Use Socialize SmartAlerts to create a viral loop in your app where a users' actions help bring other users back into your app.

Setup SmartAlerts¶

Step 1: Enable Notifications on http://www.getsocialize.com ¶

For SmartAlerts to work they must be enabled on a compatible plan at http://getsocialize.com/apps

Select your app and click “Notification Settings”

Then select “enabled”

Note

You must enter your Android package name into the Socialize website to enable notifications

Step 2: Add Configuration to AndroidManifest.xml¶

The default configuration for Socialize needs to be augmented slightly for push notifications.

Note

Make sure you replace every occurrence of your_package_name with the package name of your app!

Add the following additional configurations to the <application.../> element of your AndroidManifest.xml

<manifest...>

    <application...>
    
        <!-- Activities Required for Socialize Push Notifications -->           
        <activity android:name="com.socialize.ui.SocializeLaunchActivity" android:noHistory="true"/>

        <!-- Socialize Notification Receiver -->
        <service android:name="com.socialize.notifications.SocializeC2DMReceiver"/>
        
        <!-- Replace your_package_name with your app package name -->
        <receiver android:name="com.socialize.notifications.SocializeBroadcastReceiver" android:permission="com.google.android.c2dm.permission.SEND">
            <intent-filter>
                <action android:name="com.google.android.c2dm.intent.RECEIVE" />
                <category android:name="your_package_name" />
            </intent-filter>
            <intent-filter>
                <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
                <category android:name="your_package_name" />
            </intent-filter>
        </receiver>

    </application>

</manifest>

Add the following additional configurations to the <manifest.../> element of your AndroidManifest.xml

<manifest...>

    <!-- Permissions required for Push Notifications -->
    <!-- Replace your_package_name with your app package name -->
    <permission android:name="your_package_name.permission.C2D_MESSAGE" android:protectionLevel="signature" />
    
    <uses-permission android:name="your_package_name.permission.C2D_MESSAGE" />
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />       
    
    <!-- Google Cloud Messaging Requires these additional permissions -->
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />     

</manifest>

The full AndroidManifest.xml should look something like this

<manifest...>

    <uses-permission android:name="android.permission.INTERNET"/>
    
    <!-- Optional but recommended -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    
    <!-- Optionally add ONE of the following to include location data in comments -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    
    <!-- Permissions required for Push Notifications -->
    <!-- Replace your_package_name with your app package name -->
    <permission android:name="your_package_name.permission.C2D_MESSAGE" android:protectionLevel="signature" />
    
    <uses-permission android:name="your_package_name.permission.C2D_MESSAGE" />
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />       
    
    <!-- Google Cloud Messaging Requires these additional permissions -->
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />             

    <application...>
    
        <!-- Base Activities Required by Socialize -->
        <activity android:name="com.socialize.ui.comment.CommentActivity"/>
        <activity android:name="com.socialize.ui.action.ActionDetailActivity"/>
        <activity android:name="com.socialize.ui.profile.ProfileActivity"/>
        <activity android:name="com.socialize.auth.facebook.FacebookActivity"/>
        
        <!-- Activities Required for Socialize Push Notifications -->           
        <activity android:name="com.socialize.ui.SocializeLaunchActivity" android:noHistory="true"/>

        <!-- Socialize Notification Receiver -->
        <service android:name="com.socialize.notifications.SocializeC2DMReceiver"/>
        
        <!-- Replace your_package_name with your app package name -->
        <receiver android:name="com.socialize.notifications.SocializeBroadcastReceiver" android:permission="com.google.android.c2dm.permission.SEND">
            <intent-filter>
                <action android:name="com.google.android.c2dm.intent.RECEIVE" />
                <category android:name="your_package_name" />
            </intent-filter>
            <intent-filter>
                <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
                <category android:name="your_package_name" />
            </intent-filter>
        </receiver>

    </application>

</manifest>

Step 3: Create an Entity Loader¶

In order for Socialize to know how to handle a notification it needs an “Entity Loader”. This is a class provided by you which tells Socialize how to load content in your app.

Refer to the Entity Loaders section for details on how to implement a Socialize Entity Loader.

Testing SmartAlerts¶

When implementing SmartAlerts it is useful to know whether all the setup steps have been completed successfully and that messages are indeed being sent.

The simplest way to verify that SmartAlerts are working for your app is to send a test message from the Socialize website.

This can be found in the dash board for your app:

Locating your Device Token¶

If you are still experiencing problems and want to post a question to our support forum, it is useful to include your device token when posting any question. To determine your device token you will first need to enable the INFO level logging in Socialize.

Refer to the Displaying debug logs in LogCat section for more information on enabling logs.

Once info logging is enabled, a new instance of your app should produce log entries that look something like this:

INFO/Socialize(15860): Not registered with GCM, sending registration request...
INFO/Socialize(15860): Registration with GCM successful: APA91bHd0aL-d75F6_7NcDf_nil8...OBg5-Ixk_8c9rg9b14fsVwvMXTy4
INFO/Socialize(15860): Registration with Socialize for GCM successful.

The “Registration with GCM successful” log entry shows the device token used for SmartAlerts

I already have a BroadcastReceiver¶

Advanced Use Only

The following section is not required for most users

If you already have a BroadcastReceiver defined in your application, you can simply call the Socialize handler in your existing broadcast receiver’s onReceive() method:

/*
 * (non-Javadoc)
 * @see android.content.BroadcastReceiver#onReceive(android.content.Context, android.content.Intent)
 */
@Override
public void onReceive(Context context, Intent intent) {
	if(!SmartAlertUtils.handleBroadcastIntent(context, intent)) {
		// Message was NOT handled by Socialize.
	}
}

Make sure however, that you add the intent filters and permissions required by Socialize to your existing receiver definition.

I am already using Google Cloud Messaging¶

Advanced Use Only

The following section is not required for most users

If you are already using Google Cloud Messaging you can simply add Socialize to your existing implementation.

The first step is to add your GCM sender ID to your socialize.properties file

# This is your current GCM Sender ID
socialize.custom.gcm.sender.id=1234567890

Next, in your GCMIntentService you simply need to give Socialize a chance to handle messages recieved by GCM:

public class MyGCMIntentService extends GCMBaseIntentService {

	@Override
	protected void onMessage(Context context, Intent intent) {
		
		if(!SmartAlertUtils.onMessage(context, intent)) {
			// Your code here
		}
	}

	@Override
	protected void onRegistered(Context context, String registrationId) {
		
		SmartAlertUtils.onRegister(context, registrationId);
		
		// Your code here
	}

	@Override
	protected void onUnregistered(Context context, String registrationId) {
		
		SmartAlertUtils.onUnregister(context, registrationId);
		
		// Your code here
	}
	
	@Override
	protected void onError(Context context, String errorId) {
		
		SmartAlertUtils.onError(context, errorId);
		
		// Your code here
	}
}

The call to SmartAlertUtils.onMessage will return true if Socialize has handled the message (that is, if the message was intended for Socialize), otherwise it can be handled by you in the normal way.