Contents

1 Beta App

1.1 When I go to the "ToDo items" tab in Beta app, the screen says "Authentication Failed"

This is currently not working now. Please check todo queue via spectator https://spectator-g7g.amazon.com/FionaSpectatorService/InspectFiona.jsp

2 KCPSDK

3 General

3.1 Where are the latest Javadocs

Java docs can be found here.

3.2 How do I get my application properly signed?

For eng builds this is the Amazon debug key https://improvement-ninjas.amazon.com/s3files/s3get.cgi/debug.keystore. For userdebug and user builds, this is the amazon release key, which is protected and you can only get signed with if you go through the nightly build. This also means that all development must be done on an eng build, so you can be signed with the correct key. Android has a good document about signing

3.3 Why am I not getting the permission, I request from DCP

You need to be signed with amazon key.

4 Getting DCP

4.1 I am getting a "Dalvik format failed" error while including the contracts jar

It is not uncommon for people to get an error like:

UNEXPECTED TOP-LEVEL EXCEPTION:
java.lang.IllegalArgumentException: already added: Lcom/amazon/dcp/common/BuildInfo;
[2012-01-11 21:47:17 - TailwindAndroidSDK] Dx at com.android.dx.dex.file.ClassDefsSection.add(ClassDefsSection.java:123)
[2012-01-11 21:47:17 - TailwindAndroidSDK] Dx at com.android.dx.dex.file.DexFile.add(DexFile.java:143)
[2012-01-11 21:47:17 - TailwindAndroidSDK] Dx at com.android.dx.command.dexer.Main.processClass(Main.java:372)
[2012-01-11 21:47:17 - TailwindAndroidSDK] Dx at com.android.dx.command.dexer.Main.processFileBytes(Main.java:346)
[2012-01-11 21:47:17 - TailwindAndroidSDK] Dx at com.android.dx.command.dexer.Main.access$400(Main.java:59)

There are a couple reasons that this can occur:

5 Messaging (Server-to-Device, Device-to-Server, TPH, SPH)

5.1 How do I force a manual sync

5.1.1 For all non-user builds

With your device connected via usb, type in your console:

adb root
adb shell am broadcast -a com.amazon.intent.SYNC

5.1.2 For Otter

  • Goto Quick Settings (press the little gear in the upper right hand corner)
  • Press "Sync" button

5.1.3 For Tate and Otter2

Settings > Applications > Sync All

5.2 I am not receiving logs in S3 Bucket after implementing DCP's device-to-server messaging Client or I am getting a TT stating "Unroutable Mesage Recieved at Device Messaging(ODOT)"

Make sure you have a server-side endpoint set up. To get started to use device-to-server message to deliver messages, follow the wiki to register the topic before testing device-to-server message in Prod. https://w.amazon.com/index.php/Digital/Delivery/Messaging/Consumers#Getting_Started

5.3 How do I verify that TPH is working

  1. To make sure that TPH session is still alive. You can go to BeatApp -> TPH Client -> This window shows the last TPH message sent out of the device and last incoming message received. (PhoneHome for device type).
  2. Or you can do "adb logcat -v time" and grep through logs for the following: "TPH Phone Home : (your device type)" to see if your device type actually gets phone home messages

6 Metrics

6.1 Why aren't my metrics showing up in PMET?

In order for metrics to show up in PMET, a few things need to happen:

  1. The metrics need to be sent to DCP on the device. You should see log lines like the following, with no error lines relating to metrics nearby:
    120419:221509 LogCat: I Amzn:com.amazon.dcp.metrics.CentralDeviceMetricsCollector::[p=817:t=2032] RecordTiming: (I) DCP:WebserviceCall:WebserviceCallTime:registerDevice=1483
  2. The metrics need to be whitelisted. Contact DMS to do that. The log lines from your metrics recording can be useful in whitelisting, because they show the exact format that will be uploaded.
  3. The metrics need to be uploaded. The device does this whenever the server tells it to, which is approximately once every 2 days for devices in the sample set. (Some devices are never told to upload.) For testing purposes, you can force uploads using the Beta app (there's a big "Upload Metrics and Logs" button on the front page).
    You can confirm whether metrics are being uploaded by entering your device serial number and type into this page in Spectator. Metric uploads have names like D01EA0A0141409X2.2012.03.30.03.00.0 (there may be uploads with similar names that contain CS, VP, or IN; those are logs, not metrics). An example metric upload.
  4. There must be enough instances of the metric reported. See this entry in the PMET docs for details.

6.2 How do I get logs from a device?

6.3 How do I write metrics?

6.4 Turn off metrics and logs

By default, metrics and logs recording are on. If you do not want to record metrics and logs at all, do the following:

  1. Go to BetaApp --> DCP Preferences --> Metrics.
    • Use "Metrics Switch" to turn on/off metrics recording
    • Use "Logs Switch" to turn on/off logs recording

Make sure to exit Beta App for this to take effect. After turning off logs recording, you will still see logs on logcat, but they are not being captured.

6.5 Verify that crash reports are uploaded

  1. Induce a crash (You can do this on an eng. build from DevTools --> Bad Behavior).
  2. Check that the crash is logged under /data/data/<app_name>/files/crashlog.amzcl
  3. Restart your app.
  4. Check that DCP has picked up that crash report by verifying that a file is created under /data/data/com.amazon.dcp/cache/upload_cache/ and the crashlog.amzcl in <app_name>/files/ is deleted.
  5. Upload metrics & logs using the Beta app.
  6. Verify in Spectator the crash report is listed.

6.6 Verify that ANR reports are uploaded

  1. Induce an ANR (You can do this on an eng. build from [DevTools --> Bad Behavior --> ANR Starting a Service] or via another method).
  2. Check that there are corresponding "system_app_anr" entries in /data/system/dropbox/ (sometimes you need to reboot first).
  3. Upload metrics & logs using the Beta app.
  4. In Spectator, you will see entries like "DropBox.system_app_anr.<app_name>".

7 OTA

7.1 Why is my device not updating to the latest build

The two main reasons that a device is not updating is that it is either not in the right "OTA Pool" (sets of devices that receive certain OTAs) or it is currently not in the correct state to get an OTA.

To check if your device is in the right pool to get an update, first do a manual sync. After this verify in Todo that an OTA GET Todo Item was produced (remember to check current, completed, or failed todo items) and make sure there is a todo item with an insertion time of when you last synced. If no item was produced you are not in the right OTA pool (unless you happen to be on the latest build).

7.1.1 You are not in the right OTA pool

You should contact otter-ota@ and ask for your device to be added to a pool.

The information you should provide is:

  • Your Serial Number (can be found in Settings > Device)
  • Your current device version (can be found in Settings > Device)
  • What type of updates you would like to receive (nightly, beta, or etc)
  • Your current OTA Pool. This can be done by using Spectator Device Lookup and looking at the "OTA Group Name" metadata.

7.1.2 You are in the right OTA pool

The high level OTA flow is that it downloads the OTA update, waits for a non-intrusive time to install (so user does not notice the update) and for the device to be in a state where it can do an OTA update (proper disk space, battery, and etc), and then installs.

To make sure that the device has downloaded or is currently downloading an update, you can use the OTA Status Tool. For this simply type ';dx' in launcher search bar. A UI should pop up with your device OTA history. Now follow these steps:

  • First look for an OTAStarted entry around the time of your manual sync. This means the device is downloading the OTA update.
  • If there is no OTA downloaded entry later, then the device has not downloaded the update. Make sure you have a good internet connection and wait.
  • If there is an OTA Downloaded entry, then the OTA is done downloading and waiting to install. Reasons that it has not updated:
    • Make sure the battery is 40% or greater.
    • Make sure you have at least 100MB free on your data partition.
    • Device has not gone idle. Leave your device alone for a bit and it should update (screen has to be off a minimum of 30 seconds).

7.2 How do I downgrade my OS?

  1. Ensure the build being installed is an eng build
  2. Open the Beta app
  3. Select "DCP Configuration"
  4. Change the "Allow OS version downgrade" setting
  5. Install the build per the usual sideloading steps
  6. Factory reset

7.3 How do I switch between eng and user/userdebug?

Sideload your new build, then factory reset. The factory reset is important; Android has bugs that cause spurious permission denials if you don't. Note that because of version-numbering conventions for the different build flavors, if you're trying to go from user/userdebug -> eng of the same build, that is technically a downgrade and you'll have to enable downgrading.

7.4 How do I app OTA?

It has its own wiki: Kindle/DCP/IndividualAppUpdates.

8 Settings / Dynamic Config

8.1 SettingsCache initial sync was waiting for ever(Got Application not responding error)

Infinite hang means you need the permission com.amazon.dcp.settings.permission.READ_SETTINGS

8.2 How do I add default settings for a device?

Please follow our wiki article that defines the process of setting up default settings on each amazon device.

9 Single Sign On (SSO)

9.1 I am getting a Security Exception, when I call methods on Token Cache or AmazonAccountManager

This basically boils down to you not having the same certificate as DCP. Make sure you are properly signed. If you know your application has been properly signed, but you recently changed build flavors (for example: userdebug->eng), you must do a factory reset since android caches certificates and does not properly change them during an upgrade.

9.2 Should I use a DMS Sub Authenticator, normal Sub Authenticator, or Central Device Type

The answer is basically that you should use the Central Device Type unless there is a good reason not too. The central device type is easier from a programmatic standpoint and is better also for device and server scaling.

Some good reasons for using a sub authenticator are:

9.3 If I am migrating to new central device type, do I need my old sub authenticator code

No, You can delete all of it. This includes the xml resources files, sub authenticator classes, and services.

9.4 How do I get notified of device registration and deregistration

9.5 How do I pop up the Add Amazon Account dialog

Here is a code sample:

    AccountManager acctMan = AccountManager.get(Main.this);

    AccountManagerFuture<Bundle> resultFuture = acctMan
                                                     .addAccount(AccountConstants.AMAZON_ACCOUNT_TYPE,
                                                                          null,
                                                                          null,
                                                                          null,
                                                                          null,
                                                                          null,
                                                                          null);

    try
    {
           Bundle result = resultFuture.getResult();
           Intent addAccount = result.getParcelable(AccountManager.KEY_INTENT);
           startActivity(addAccount);
     }
     catch (OperationCanceledException e)
     {
           // handle exception
     }
     catch (AuthenticatorException e)
     {
          // handle exception
     }
     catch (IOException e)
     {
          // handle exception
     }


9.6 We need to figure out whether or not the device is registered or deregistered.

AmazonAccountManager.hasAmazonAccount() returns true if there is a primary Amazon account registered to this device.

See full documentation in our java doc here

Note: If you are also trying to get the primary account, use AmazonAccountManager.getAmazonAccount.

The following will NOT guarantee to return the primary account.

Account[] accounts = AccountManager.get(this.context).getAccountsByType(AccountConstants.AMAZON_ACCOUNT_TYPE);

Account amznAccount = accounts[0];

9.7 How do I get the device name?

AmazonAccountManager mgr = new AmazonAccountManager(getApplicationContext());

mgr.getUserData(mgr.getAmazonAccount(), AccountConstants.KEY_DEVICE_DEVICE_NAME);

9.8 How do I get the system device type?

// do not do this on your application's main thread. It will cause you to ANR if you do.

String deviceType = tokenCache.blockingFetchToken(AccountConstants.TOKEN_TYPE_DEVICE_TYPE);

10.1 How to handle the "Not Connected Exception" after an SNDS webservice call.

The SNDS linked status on the client reflects the user linked state for Facebook or Twitter. This status may not reflect the case where the user disconnects from a social network from another device. The linking status on the SNDS server side would reflect the unlinked state, but the client would yet to be updated.

When an application then tries to make a SNDS webservice call, it will get a "Not Connected Exception".

The right way for the application to handle the "Not Connected Exception" is to call the SNDSCilent.parseSNDSResponse API. DCP will update the SNDS link status to unlinked and broadcast the change.

The application can raise the intent com.amazon.kindle.otter.settings.LinkSocialNetwork to launch Social Network linking flow in MyAccount (with optional parameters to specify whether FB or Twitter).