Digital Mementos Developer's Guide

Digital Mementos is an Intel® Cloud Services Platform sample application that enables users to plan a trip, find points of interest (POI) in the region, and keep a trip journal. During the trip, users can get helpful information about POI, such as a description of the location, hours of operation, and a map. They can also post check ins and leave geo messages. Digital Mementos provides cross-platform, transparent consumer experiences in the form of Windows* 8, Android*, and web client applications.

Digital Mementos consists of the following components:

Native Clients

Windows 8
Android

Web Clients

Geo Messages
Facebook activities

Server Side

Application specific services: trips, Geo Messages
Intel Cloud Services Platform Services: Intel® Identity Services, Location Based Services, and Context Services
Third-party services: Facebook

This guide describes how to build and install all native client components.

Source Code Packages

Two client components are delivered in two .zip files, a Windows 8 and an Android zip. These files have the following structures.

Windows 8

Android

This source code package includes all the components built by Intel for the native client applications. However, to build and install these client applications requires some third-party components. Detailed instructions can be found below.

Windows 8 Client

Requirements

Windows 8 RTM
Visual Studio* 2012

Client Installation Steps

Unzip the source code package.
Copy the Windows 8 client directory from the source code package to your Windows 8 system.
Open the Digital Mementos solution file using Visual Studio 2012.
Before running the application, in Visual Studio turn off the Access is denied JavaScript* exception. To do this, select Debug> Exceptions. Then, under JavaScript Runtime Exceptions, uncheck the Thrown box corresponding to Access is denied:

Doing this will ensure that the exception is not thrown if it is user-handled. This is a correction to the default debug settings in Visual Studio and it is required because the location sensor is used by Digital Mementos, When a user does not allow location to be used, this exception gets thrown even if it is handled in the code.
Build the solution and follow Visual Studio instructions to deploy to a Windows 8 system.

The Windows 8 client application is completely self-contained and does not require separate third-party components.

Android Clients

Requirements

Android-based phone running version 4.0 or above.
Eclipse IDE: download from http://www.eclipse.org/, according to your operating system.
Eclipse Android plugin: http://developer.android.com/tools/sdk/eclipse-adt.html
Android SDK: http://developer.android.com/sdk/index.html
Facebook SDK for Android: https://developers.facebook.com/android/
Intel Context Framework Service: binary distributed with the source code package.

Clients

The source code package for the Digital Mementos Android clients consists of the following files:

There are two native client applications: Travel Companion and Geo Messages. The Travel Companion application requires a sub-component called Context Sources, which is part of the tree and needs to be built first. There are also additional third-party components and libraries that must be built first. The following section explains the process.

Set Up the Development Environment

Install Eclipse IDE.
Install Android SDK.
Install ADT Plugin.

Building Steps

Using the Eclipse IDE, select your workspace as usual.
Download the Facebook SDK for Android and extract the facebook folder from the zip file.
Import the facebook folder into the existing workspace (default name for this project is FacebookSDK).

Select File > Import to import the project.
Select Android > Existing projects into workspace.

Include the Google APIs in project properties.
Run Android Tools> Fix Project Properties.
Build the FacebookSDK project.
Import the Context Sources folder into the existing workspace.

Select File > Import.
Select Android > Existing projects into workspace.

Locate the path for the TravelCompanion project and import it into the workspace.

Select File> Import.
Select Android > Existing projects into workspace.

Add the FacebookSDK project as an Android library to the TravelCompanion project. To do this, in the project, select Properties> Java Build Path> Projects, and add FacebookSDK:

Then, still on the TravelCompanion properties page, select the Android tab and add the FacebookSDK library:
Copy android-support-v13.jar from the Android SDK to the libs directory of the TravelCompanion project and refresh (press F5):
Run a "clean and build" to ensure everything works: select Options> Project> Clean and then select your project and click OK.
Locate the LocationMessaging project and import it into the Workspace.

Select File > Import.
Select Android > Existing Projects into Workspace.

Download the latest version of the HttpClient software from http://hc.apache.org/httpcomponents-client-ga/ (e.g. httpcomponents-client-4.2.2-bin.zip).
Extract httpmime-4.2.2.jar and copy it to the libs directory of the LocationMessaging project.
Refresh the project.
Run a "clean and build" to ensure everything works: select Options> Project> Clean and then select your project and click OK.

Deploy the Application to Your Android Phone

Build the Digital Mementos native clients for Android according to the Building Steps section.
Your Android phone should be running version 4.0 or above.
Go to Settings > Developer Options and check Debug USB. After that, you can use your mobile device to execute the Android app from Eclipse.
Download and install Android USB drivers as necessary.
Deploy Intel Context Framework Service (CAC Service) to your Android based phone:
adb install IntelContextFrameworkAndroidPR3Service-2.9.13668.apk
For this step to be successful, you need to make sure that adb is in your path.
Start the service.
Deploy the file scanner context source:

Right-click the FileScannerCS project and select Run As > Android Application. (If a new window opens, select your phone and click OK to run the application.)
Locate FileScannerCS.xml in the context sources folder of the source code package and deploy it using the following command:
adb push FileScannerCS.xml /data/data/com.intel.ssg.cac/app_cacsources/

Deploy the categories context source like this:

Right-click the CategoriesCS project and select Run As > Android Application. If a new window opens, select your phone and click OK to run the application.
Locate CategoriesCS.xml in the context sources folder of the source code package and deploy it using the following command:
adb push CategoriesCS.xml /data/data/com.intel.ssg.cac/app_cacsources/

Restart CAC service to register the context sources.
Deploy the Geo Messages client application like this:
Right-click the LocationMessaging project and select Run As > Android Application. If a new window opens, select your phone and click OK to run the application.
Deploy the Travel Companion client application like this:
Right-click the TravelCompanion project and select Run As > Android Application. If a new window opens, select your phone and click OK to run the application.

Travel Companion and Geo Messages Android clients should be up and running now! For more details about using the application, please refer to the Using Digital Mementos section below.

Using Digital Mementos

After you have successfully deployed the desired client applications, you should be ready to start interacting with the application.

To use any of these clients, you first need to sign in using your Intel Identity Services login credentials. You will also need to use a Facebook account, so the application can query for all the corresponding Facebook attributes such as comments and likes for any given trip.

These steps summarize the required initial application permissions flow:

1: Log into Facebook.

2: Log into Intel Identity Services.

3: Set up Windows 8 location sensor permissions.

4: Go to Digital Mementos application settings and set up Intel Identity Permissions for this application.

5: Start using Digital Mementos!

You will also need to get a developer key for Weather Underground if you want to take advantage of the Weather Context Source provided with the application.

For more information about Digital Mementos, please refer to the Digital Mementos white paper.

Troubleshooting

The following are some tips for solving common issues found when building, deploying and using Digital Mementos:

Windows 8 client does not have permissions to read/write data from Intel Context Services (this applies to the Android clients too).

Go to the settings menu of Windows 8 client and click the Intel Identity Services Permissions button to access the Intel Identity Services dashboard.

Once the Intel Identity Services dashboard loads, please log in using your credentials (or register if you haven’t done so before), and select Manage App Access:

Next, open the drop-down menu for DM Metro PROD to set the stored data access permissions:

Click Allow to grant access to the application:

Please notice that redeploying the application creates a new instance of it in the dashboard that you will then need to set the permissions to.

Access denied JavaScript exception is thrown:

This happens when a user has not yet granted this application permission to use the Windows 8 location sensor. Uncheck the Break when this exception type is thrown box and click Continue, and this particular exception will not occur again. This is handled in the code itself, but it is necessary to correct the Visual Studio default debug exception settings.

Do I need a Facebook account to be able to run Digital Mementos?

Yes. You can certainly log into the Intel Identity Services using any supported account, but Digital Mementos requires interacting with Facebook.

The Upcoming and Past trips sections on the main page don’t show my trips.

This can happen if you're using a slow Internet connection and you have created a large number of trips. In order to view your trips, the page needs to be refreshed by navigating to some other page.

The city I am searching for does not appear as an option in the auto-complete window.

Only cities supported by the Digital Mementos current content provider (i.e. WCities) can be used.

The name of the trip does not match the city you're searching for.

This mismatch happens because by default, the application assumes that the trip that was last being used is the currently active trip. If you want to create a new trip, click the current trip name and select “Create a new trip”:

If you want to add additional points of interest (POI) to an existing trip, first find that trip in the list of existing trips, select that trip, and click the “Find more stuff” link in the trip toolbox:

The map does not fully render.

Try again, and the map should be able to complete the rendering.

I get an HTTP 500 error after sharing a trip and trying to access the shared trip page.

Please, make sure that you have signed in to Facebook. Sign in is required for you to be able to access any shared trip pages.

The POI I am looking for does not show up in the list.

The sample application only supports a subset of all POI available from the content provider for any given city.

Pictures are not being saved as part of the trip using the Windows 8 client.

Please make sure to close the Edit Photos window (top right) so that all picture changes are processed:

Android-Specific Issues

My device doesn’t appear in the Android Device Chooser list in Eclipse.

Enable Debug Mode in the Android menu: go to Settings> Developer debugging and make sure the USB debugging option is checked.

When I execute the adb command I get the message,“bash: adb command not found”

You need to add the adb command to the PATH.

When I try to install the ADT plugin, I receive an error saying there are prerequisites missing that are necessary to install this feature.

This happens because some of the Eclipse update sites are not enabled. To fix this, do the following:

Help> Install New Software.
Click Available Sites.
Press OK and retry the installation.

When I launch the application, I get an error in the console saying that the Facebook.apk is not there. When the application is executed, I get the classNoDefFoundException when it tries to use the Facebook classes.

Follow these steps:

Right-click the Facebook project and select Properties.
Go to the Android tab.
Uncheck the is Library checkbox.
Right-click the Facebook project and select Run As> Android Application. In this step, it is not necessary to install the apk.
Repeat the first two steps.
Check the is Library checkbox.
Right-click in the Digital Mementos project.
Go to the Android tab.
In the Library, if the Facebook project is present, remove it.
Click Add.
Select the Facebook project again.
Run the application.

Whenever I take a photo, it is not uploaded and I get an error message saying the auto-upload process is not running.

To solve this error:

Make sure the Photo CS is deployed.
Restart cacService.

Windows 8 -Specific Issues

My Windows 8 Client can’t connect to services.

Make sure you are connected to the Internet. You may need to set up proxy in Internet Explorer*. It may also be possible that the Facebook or Intel Identity Services are down.

When I launch the application, do I have to log in with my Facebook credentials?

Yes. You must log in with your Facebook credentials to access Digital Mementos functionality.

Do I need to log in again using Intel Identity Services?

Yes, you need to log in to Intel Identity Services, but you can log in with your Facebook, Yahoo, or Google credentials.

I cannot see weather information on the main page.

You need to get a Weather Underground key (see http://www.wunderground.com/weather/api/) and use that in the app to get weather information.