Home
Catch Notes is the easiest way to take notes on the go! The Catch Notes application features include:
- Synching notes to the web
- Attachment of photos, voice recordings, and other files
- Organizing notes with tags
- Tagging notes with location
This document explains how you can use these abilities from within your own Android application to save user data into the Catch system.
If you have any questions about this developer documentation, please contact developer@catch.com.
Catch Notes is built on a distributed storage engine designed specifically to support mobile environments. The Catch Notes clients keep data in sync between the server and the mobile device; if there are multiple mobile devices signed into the same account (or into accounts which share one or more “spaces”), then changes made on one device will be rapidly copied across all other devices.
We encourage third parties to integrate with the Catch system. The HTTPS server APIs are documented at https://developer.catch.com/ and provide all the capabilities used by our own mobile clients. For simple mobile applications, however, it is easier to interface with the Catch Notes Android app and let it handle the intricacies of integrating with the server.
We support this through a series of Android Intents. For example, there is an intent to “create a new note”: you send new data to the Catch Notes app, which will store that data and synchronize it to the user’s account on our server. There are also intents that request Catch Notes to display selected data, including single notes.
You can use the Android intents directly in your own code - it only requires a few lines - but there are a few details (such as detecting whether Catch Notes is already installed) that require a little more thought, so we’ve provided this Android library to wrap these details and make it as simple as possible to use Catch Notes with your Android application.
This document is intended for Android developers and assumes the reader is comfortable with Java programming and has a basic knowledge of the Android SDK.
After reading this document you will be able to:
- Determine whether or not Catch Notes is installed on the target device
- Create a new Note using the Catch Notes intent
- Create a new Location Based Note using the Catch Notes intent
- Attach an image to a new note
- View a list of notes that you created
- Position the cursor within a new note
This document references sample code that is available via github. The source can be found in the CatchNotesIntegration directory of the following repository:
URL: http://github.com/catch/android-intent
GIT: git://github.com/catch/android-intent.git
The CatchNotesIntegration project is a sample Eclipse based project to help you quickly get started. The sample demonstrates how to create a note using the Catch Notes v2.0 (or later) Intent. Please be sure you have the Android SDK 1.5 or later installed in order to run the sample application. Upon running the Catch Notes Integration activity you will see the following screen:
When you click any button the Activity will determine whether or not the Catch Notes application is installed. If the application is not installed, you will be presented with an option to install the application. If the installed version of Catch Notes does not support the Notes intent you will be given the option to upgrade.
Clicking Install or Upgrade on either dialog will redirect you to the Catch Notes application in the Android market as illustrated below.
If Catch Notes is installed then the intent will be launched. The following table describes the action taken when each button in the sample activity is pressed.
| Button | Action when Pressed | Screenshot |
|---|---|---|
| Create a Simple Note | Creates a standard note in Catch Notes with some text and a tag. |  |
| Create a Note with Image | Prompts you to select an image from your gallery and then creates a new image based note. |  |
| Add a Quick Note | Creates a new note in Catch Notes that is automatically saved without pausing in the editor. Depending on the speed and memory state of the particular device, the Catch activity may not even animate into view. It is advised that you provide your users feedback (via a Toast popup or other mechanism) that the quick note was saved. |  |
| Create a Location Tagged Note | Creates a note that is tagged with a location. |  |
| View Notes | Displays a list of notes with the sample tag. |  |
| Cursor Positioning Example | Demonstrates how to position the cursor in a new Catch Note. |  |
| Record a Vocie Note | Demonstrates how to record a new voice note. | |
| Add a Reminder Note | Demonstrates how to add a new note, allowing the user to interactively choose a reminder date & time. |
The IntentIntegrator class allows you to create a Catch Note with only two lines of code. The class automatically handles install and upgrade checks for the Catch Notes application.
In order to use the CatchNotesIntent class you will need to copy the following files from the sample project into your project:
- Add a com.catchnotes.integration package and copy IntentIntegrator.java into the package
- Add a com.catchnotes.intent package and copy CatchIntent.java into the package
- Copy market_icon.png into your project’s res\drawable folder
- Copy CatchIntent.xml into your projects res\values folder
You can create a simple note using the IntentIntegrator class as follows:
IntentIntegrator notesIntent = new IntentIntegrator(context);
notesIntent.createNote("#sample");
You can create a location tagged note using the IntentIntegrator class as follows:
// Create a sample location
Location location = new Location(LocationManager.NETWORK_PROVIDER);
location.setLatitude(30.267153);
location.setLongitude(-97.743061);
// Create the note
IntentIntegrator notesIntent = new IntentIntegrator(context);
notesIntent.createNote("#sample", location);
You can view / filter notes that have been created for a specific tag as follows:
IntentIntegrator notesIntent = new IntentIntegrator(context);
notesIntent.viewNotes("#sample");
You can specifiy the position of the cursor as the last parameter to the createNote method as follows:
IntentIntegrator notesIntent = new IntentIntegrator(context);
notesIntent.createNote("#sample", 2); // Cursor will be positioned after ‘s’
//…
notesIntent.createNote("#sample", location, 3); // Cursor will be after ‘a’
You can create a quick note (which will automatically save and return to your activity) as follows:
IntentIntegrator notesIntent = new IntentIntegrator(context);
notesIntent.createNote("My Quick Note\n\n#sample", true);
Note that you should display a Toast after creating the quick note so that the user receives feedback that the note has been created.
To include an image with your note, create a Uri object that identifies the location of the image file you’d like to share. This location needs to be globally readable — e.g., on the SD card.
IntentIntegrator notesIntent = new IntentIntegrator(context);
Uri imageUri = Uri.parse("file:///some/path/to/your/image.jpg");
notesIntent.createNote("My Image Note\n\n#sample", imageUri, "image/jpeg", null);
To create a new voice note with an audio file that already exists (as opposed to using the action below describing how to make Catch Notes perform the recording interactively), create a Uri object that identifies the location of the audio file you’d like to share. This location needs to be globally readable — e.g., on the SD card.
IntentIntegrator notesIntent = new IntentIntegrator(context);
Uri audioUri = Uri.parse("file:///some/path/to/your/recording.3gp");
notesIntent.createNote("My Voice Note\n\n#sample", audioUri, "video/3gpp", true);
Note that Catch will enforce a MIME filter (“audio/*”, “video/*”, “application/ogg”) for voice attachments. We recommend you use common formats and codecs (AMR inside 3GPP, or AAC inside MP4, for example) for best playback compatibility across all Catch clients. Yes, “video/*” can be used for voice notes — only audio tracks will be presented to the user. (Many common multimedia container formats identify as video MIME types.)
If you prefer not to use the IntentIntegrator class you can invoke the Catch Notes Intent directly within your application. This section describes the steps required to invoke the Catch Notes Intents, using the implementation from within IntentIntegrator as an example. You can always tailor the Intent creation and usage to best fit your own application design.
Before invoking the intent you must verify that a suitable version of Catch Notes is installed. This can be done as follows:
private static final String NOTES_PACKAGE_NAME = "com.threebanana.notes";
private static final int NOTES_MIN_VERSION_CODE = 54;
// Verify that correct version of notes is installed
try {
PackageInfo packageInfo = context.getPackageManager().getPackageInfo(
NOTES_PACKAGE_NAME, PackageManager.GET_ACTIVITIES);
if (packageInfo.versionCode < NOTES_MIN_VERSION_CODE) {
// Upgrade Required
}
} catch (NameNotFoundException e) {
// Install Required
}
If an install or upgrade for Catch Notes is required you can display the corresponding Android Market page as follows:
private static final String NOTES_PACKAGE_NAME = "com.threebanana.notes";
private static final String NOTES_MARKET_URI =
"http://market.android.com/search?q=pname:" + NOTES_PACKAGE_NAME;
Uri uri = Uri.parse(NOTES_MARKET_URI);
Intent intent = new Intent(Intent.ACTION_VIEW, uri);
intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET);
context.startActivity(intent);
If a suitable version of Catch Notes is installed you can create a note as follows:
public void createNote(String message, Location location, long reminder, int cursorPosition, boolean autoSave, Uri mediaUri, String mimeType, boolean isVoiceNote) {
// Verify that correct version of notes is installed
if (!isNotesInstalled()) {
return;
}
// Create the Intent
Intent intent = new Intent();
// This action signifies you want to add a new note to the user's notebook
intent.setAction(CatchIntent.ACTION_ADD);
// Mandatory. This will be the content of the note. The object should be
// a String.
intent.putExtra(Intent.EXTRA_TEXT, message);
// Mandatory; EXTRA_SOURCE identifies your app as the source
// for this note. Don't use the example below; please arrange with the
// Catch development team for the string you will use to identify your
// app. The object should be a String.
intent.putExtra(CatchIntent.EXTRA_SOURCE, "Catch Intent Test Utility"); // TODO: *** change this to your own source string! ***
// Mandatory; EXTRA_SOURCE_URL identifies a URL which will be presented
// in conjunction with your EXTRA_SOURCE field. This should link to your
// site, app, or other relevant web asset. The object should be a String.
intent.putExtra(CatchIntent.EXTRA_SOURCE_URL, "https://catch.com/"); // TODO: *** change this to your own source URL! ***
// Optional; if EXTRA_TITLE is supplied it will appear in the
// titlebar of the note editor activity in Catch Notes. The object should be
// a String. It will appear as:
//
// New note: <your title>
//
intent.putExtra(Intent.EXTRA_TITLE, "testing Catch Intents"); // TODO: *** change this to your own title (or leave the extra out) ***
// Optional: include a media attachment. The attachment Uri should be
// accessible to external packages (i.e., don't point to content private
// to your application).
if (mediaUri != null) {
intent.putExtra(Intent.EXTRA_STREAM, mediaUri);
// If you don't supply a MIME type, Catch Notes will attempt to
// figure it out based on ContentProvider hints or the filename extension.
//
// Note that the Catch sync servers do strict MIME type checking; if you
// misrepresent the MIME type of a media attachment, your users will not be
// able to sync them.
if (mimeType != null) {
intent.setType(mimeType);
}
// Note that Catch Notes will enforce restrictions of what MIME types
// can be considered voice recordings: "audio/*", "video/*", "application/ogg".
// Also note that not all media files that match these descriptors will
// play in the player controllers of Catch Notes (Android, iOS, or web).
// Only certain common codecs and container formats are supported.
// For Android, we suggest "video/3gpp" with AMR narrowband audio or
// "video/mp4" with AAC audio for best compatibility.
//
// Audio attachments that do not have this voice note flag set will
// be treated like regular file attachments to the note.
if (isVoiceNote) {
intent.putExtra(CatchIntent.EXTRA_VOICE, true);
}
}
// Optional: include a location. The object should be a Location.
if (location != null) {
intent.putExtra(CatchIntent.EXTRA_LOCATION, location);
}
// Optional: include a reminder. This value is standard system
// millisecond time (milliseconds since January 1, 1970 00:00:00 UTC)
if (reminder > System.currentTimeMillis()) {
intent.putExtra(CatchIntent.EXTRA_REMINDER, reminder);
}
// Optional: specify a cursor position for the editor. The type should
// be an int.
if (cursorPosition >= 0) {
intent.putExtra(CatchIntent.EXTRA_CURSOR_POSITION, cursorPosition);
}
// Optional: specify autosave. Intents with autosave set will send the
// note and its contents, save it immediately, and return to your
// activity. You may want to provide feedback to your users that the
// action completed. The type should be a boolean.
if (autoSave) {
intent.putExtra(CatchIntent.EXTRA_AUTOSAVE, true);
}
// Start the Intent
startNotesIntent(intent);
}
If a suitable version of Catch Notes is installed you can view / filter notes as follows:
public void viewNotes(String tag) {
// Verify that correct version of notes is installed
if (!isNotesInstalled()) {
return;
}
// Prefix with hash if necessary
if (!tag.startsWith("#")) {
tag = "#" + tag;
}
// Create the Intent
Intent intent = new Intent();
intent.setAction(CatchIntent.ACTION_VIEW);
intent.putExtra(CatchIntent.EXTRA_VIEW_FILTER, tag);
intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
// Start the Intent
startNotesIntent(intent);
}
If a suitable version of Catch Notes is installed you can let the user record a new voice note as follows:
public void recordVoice(String message) {
// Verify that correct version of notes is installed
if (!isNotesInstalled()) {
return;
}
// Create the Intent
Intent intent = new Intent();
intent.setAction(CatchIntent.ACTION_ADD_VOICE);
// Optional: text to include with the voice note.
if (message != null) {
intent.putExtra(Intent.EXTRA_TEXT, message);
}
// Start the Intent
startNotesIntent(intent);
}
If a suitable version of Catch Notes is installed you can let the user record a new reminder date/time and add a note with it set as a reminder as follows:
public void addReminder(String message) {
// Verify that correct version of notes is installed
if (!isNotesInstalled()) {
return;
}
// Create the Intent
Intent intent = new Intent();
intent.setAction(CatchIntent.ACTION_ADD_REMINDER);
// Optional: text to include with the reminder note.
if (message != null) {
intent.putExtra(Intent.EXTRA_TEXT, message);
}
// Start the Intent
startNotesIntent(intent);
}