An API for CM Home.

CM Home is an open-source content aggregation application built in the spirit of Google Now that can display any type of Card that is compatible Cardslib. Right now, it displays a card for each DashClock extension installed on the device, but starting now, third party applications can publish cards as well!

This repository hosts both the SDK for developers to integrate and the related classes for hosting cards published from external applications implementing the SDK.

CM Home takes a central place on the user's device as it is directly accessible with a left swipe from the Trebuchet launcher that ships with CyanogenMOD. We expect that the best extensions will publish cards with relevant and engaging content at just the right time.

The SDK was built to allow developers to share content with as little code as possible. Each application hosts a ContentProvider that stores information about the current cards that is read by CM Home in real time as data is added.

You can view the full JavaDocs here

The most up to date jar for the SDK is available here: cmhome-api_v1_0.jar. Download and import this jar to get started.

Before you can publish cards, there are a few prerequisites to take care of:

1. Your application must declare the org.cyanogenmod.launcher.home.api.FEED_PUBLISH permission in AndroidManifest.xml:

   <uses-permission
       android:name="org.cyanogenmod.launcher.home.api.FEED_PUBLISH" />

2. You must declare CmHomeContentProvider in your AndroidManifest.xml. Please note that the following attributes must be set to specific values:

   android:name - set this to the fully qualified class name of CmHomeContentProvider: "org.cyanogenmod.launcher.home.api.provider.CmHomeContentProvider"

   android:label - You must define a string to label this ContentProvider.

   android:authorities - This must be set to your package name.cmhomeapi as in the example below.

   android:readPermission and android:writePermission - Must be set as in the example below.

   <provider android:name="org.cyanogenmod.launcher.home.api.provider.CmHomeContentProvider"
             android:label="@string/provider_name"
             android:authorities="org.cyanogenmod.launcher.home.api.sdkexample.cmhomeapi"
             android:enabled="true"
             android:exported="true"
             android:readPermission="org.cyanogenmod.launcher.home.api.FEED_HOST"
             android:writePermission="org.cyanogenmod.launcher.home.api.FEED_HOST" />

To publish cards to CM Home, nearly everything you need is in the CardData class. CardData contains data representing a single card that can appear in CM Home.

CardData includes many possible fields, and not all of them are required. The idea is that an extension application can publish whatever data or content they have available, and CM Home will do it's very best to find the best Card UI for the data available. At minimum, a card should have a ContentCreatedDate and a Title. More Card types will be created in the future, so publish as much data as you have, so that they will be used in rich ways within CM Home.

Instantiate a new CardData, set the fields you are interested in, and publish!

// A card about an exciting news article!
Date now = new Date();
CardData cardData = new CardData("CyanogenMod releases a sweet new SDK!", now);
cardData.setBodyText("It's pretty awesome, click to read more.");

// Create an Intent to be launched when the user clicks the Card.
Intent cardClickIntent = new Intent(Intent.ACTION_VIEW,
                                                   Uri.parse("http://www.cnn.com/articles/awesome_cm_sdk.html"));
cardData.setCardClickIntent(cardClickIntent, false);

// Publish the card for immediate display in CM Home!
// Assuming this refers to an Activity or Service
cardData.publish(this);

After you have published a card to CM Home, you can easily update it in place and publish the updates:

cardData.setTitle("Breaking news! CyanogenMod just got even more awesome.");

// Still assuming this refers to an Activity or Service
cardData.publish(this);

That's it, now the same card from above will be updated with a new title.

Sometimes a Card is no longer relevant, maybe the optimal time for display has passed. Or, perhaps the user has reconfigured your application to publish different cards. Just call unpublish(Context):

// Say goodbye!
cardData.unpublish(this);

You can attach images to a CardData by creating instances of CardDataImage. These are general purpose images that can be used by the card in CM Home for display.

Example use cases would be to display an image attached to a news article. Or, for showing images posted by a Social Media friend.

Right now, there is no upper bound, but generally CM Home cards will probably not have enough room to display more than 6 images.

Let's add an image to that article!

// Let's pretend we have a method for this
Bitmap articleBitmap = getArticleImage();

CardDataImage image = new CardDataImage(cardData);
image.setImage(articleBitmap);
cardData.addCardDataImage(image);

// Publish that card!
cardData.publish(this);

If your image is retrievable with a Uri (Content, file and internet Uris accepted!), you can just pass that to CardData using addCardDataImage:

cardData.addCardDataImage("http://www.cnn.com/images/cyanogenmod_rules.jpg");
cardData.publish(this);

At any time, to retrieve the Cards that are currently published for your application, just call the static method of CardData, getAllPublishedCardDatas:

List<CardData> allTheCards = CardData.getAllPublishedCardDatas(this);

Now that you have a reference to the cards, feel free to update them or unpublish them as you see fit!

CM Home can also modify the cards hosted by your application. Currently, the only time this will happen is when a card is deleted by the user or by the application. For some applications (though not all), this can be an important event to handle.

To receive a Broadcast when a card is deleted:

1. Subclass CmHomeCardChangeReceiver and override the onCardDeleted method as shown below:

   /**
    * An extension of CmHomeCardChangeReceiver, that implements the callback for
    * when a card is deleted.
    */
   public class MyCardChangeBroadcastReceiver extends CmHomeCardChangeReceiver{
       public static final String TAG = "CardDeletedBroadcastReceiver";
   
       @Override
       protected void onCardDeleted(Context context, CardData.CardDeletedInfo cardDeletedInfo) {
           Log.i(TAG, "CM Home card was deleted: id: " + cardDeletedInfo.getId()
                      + ", internalID: " + cardDeletedInfo.getInternalId()
                      + ", authority: " + cardDeletedInfo.getAuthority()
                      + ", globalID: " + cardDeletedInfo.getGlobalId());
       }
   }

   The CardDeletedInfo object passed to onCardDeleted contains the necessary identifying information to handle a deleted card.

2. Add your new BroadcastReceiver subclass to your AndroidManifest.xml:

    <receiver
               android:name="org.cyanogenmod.launcher.home.api.sdkexample.receiver.MyCardChangeBroadcastReceiver"
               android:permission="org.cyanogenmod.launcher.home.api.FEED_HOST">
                     <intent-filter>
                         <action android:name="org.cyanogenmod.launcher.home.api.CARD_DELETED" />
                     </intent-filter>
           </receiver>

   Make sure to protect this BroadcastReceiver with the FEED_HOST permission, as defined above. Only CM Home will hold this permission, so malicious apps cannot send bogus Broadcasts.

CM Home will, at times, send a Broadcast to inform all applications that have implemented the SDK that Cards should be updated. This may occur in the background to keep the content at it's freshest. However, the most likely use case is that the user has opened CM Home and the newest content should be published immediately.

This is the time to remove stale content, update existing content, and publish new content. However, if nothing has changed for your application since the last time you published, this Broadcast can be safely ignored.

To handle this request:

1. Add an overriden method implementation for onRefreshRequested(Context context) to MyCardChangeReceiver that we defined above:

   /**
        * An extension of CmHomeCardChangeReceiver, that implements the callback for
        * when a card is deleted, and handles the refresh request Broadcast.
        */
       public class MyCardChangeBroadcastReceiver extends CmHomeCardChangeReceiver{
           public static final String TAG = "CardDeletedBroadcastReceiver";
   
           @Override
           protected void onCardDeleted(Context context, CardData.CardDeletedInfo cardDeletedInfo) {
               Log.i(TAG, "CM Home card was deleted: id: " + cardDeletedInfo.getId()
                          + ", internalID: " + cardDeletedInfo.getInternalId()
                          + ", authority: " + cardDeletedInfo.getAuthority()
                          + ", globalID: " + cardDeletedInfo.getGlobalId());
           }
   
           @Override
           protected void onRefreshRequested(Context context) {
               // Update your cards now!
           }
       }

2. Add the intent filter to your receiver declaration in AndroidManifest.xml as defined above:

    <receiver
               android:name="org.cyanogenmod.launcher.home.api.sdkexample.receiver.MyCardChangeBroadcastReceiver"
               android:permission="org.cyanogenmod.launcher.home.api.FEED_HOST">
                     <intent-filter>
                         <action android:name="org.cyanogenmod.launcher.home.api.CARD_DELETED" />
                         <action android:name="org.cyanogenmod.launcher.home.api.REFRESH_REQUESTED" />
                     </intent-filter>
           </receiver>

• CM Home SDK Example - A super simple example project that just publishes test cards with buttons