Skip to content

Home

Jump to bottom Edit New page
JeffAtCatch edited this page May 7, 2011 · 14 revisions

Catch Notes Integration

Introduction

Catch Notes is the product formerly known as “3banana Notes”. Our company name has also changed from Snaptic to Catch.com, Inc. We’re in the process of updating our documentation; please let us know if there is any confusion.

Note that Catch Notes 2.0 and later does still support the previous “SnapticIntent” intents. Code written against that earlier interface should still work, although we do encourage people to update to the new CatchIntent as soon as reasonably possible.

Overview

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 integrate Catch Notes 2.0 or later into your own Android application to allow users to seamlessly create notes on the fly.

Intended Audience

This document is intended for Android developers and assumes the reader has a basic knowledge of the Android SDK.

Objectives

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

Sample Code

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

Getting Started

Sample Project

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.

Using the IntentIntegrator Class

Overview

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.

Pre-Requisites

In order to use the CatchNotesIntent class you will need to copy the following files from the sample project into your project:

  1. Add a com.catchnotes.integration package and copy IntentIntegrator.java into the package
  2. Add a com.catchnotes.intent package and copy CatchIntent.java into the package
  3. Copy market_icon.png into your project’s res\drawable folder
  4. Copy CatchIntent.xml into your projects res\values folder

Creating a Simple Note

You can create a simple note using the IntentIntegrator class as follows:

IntentIntegrator notesIntent = new IntentIntegrator(context);
notesIntent.createNote("#sample");

Creating a Location Tagged Note

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);

Viewing Notes

You can view / filter notes that have been created for a specific tag as follows:

IntentIntegrator notesIntent = new IntentIntegrator(context);
notesIntent.viewNotes("#sample");

Positioning the Cursor within a new Note

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’

Creating a Quick Note

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.

Creating an Image Note

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);

Creating an Voice Note with a Pre-recorded Audio File

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.)

Advanced Integration

Overview

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.

Verifying Catch Notes is Installed

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
}

Displaying the Catch Notes Market Page

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);

Creating a Catch Note

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);
	}

Viewing Notes

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);
	}

Recording Voice Notes

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);
	}

Interactive Reminder Notes

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);
	}
Add a custom footer
Add a custom sidebar
Clone this wiki locally