FirefoxData for Android

FirefoxData is an Android library that allows an application to easily access a selection of the user's Firefox Account data:

• History
• Bookmarks
• Passwords

This library is also available on iOS (TODO: link).

Installation

Be sure jcenter is present in your gradle repositories and add the following to your module's build.gradle:

compile 'org.mozilla.fxa-data:thirdparty:0.0.1'
compile 'org.mozilla.fxa-data:gecko:0.0.1'
compile 'org.mozilla.fxa-data:download:0.0.1@aar'

Quick start

Below is the simplest implementation, based on SimpleExampleActivity, which is one of the examples in the examples/ module.

public class MainActivity extends AppCompatActivity {
    private FirefoxDataLoginManager loginManager;

    @Override
    protected void onCreate(final Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main); // update for your implementation.

        // Store a reference to the login manager,
        // which is used to get a FirefoxDataClient.
        loginManager = FirefoxData.getLoginManager(this);

        final FirefoxDataLoginManager.LoginCallback callback = new ExampleLoginCallback();
        if (!loginManager.isSignedIn()) {
            loginManager.promptLogin(this, "Your app name", callback);
        } else {
            loginManager.loadStoredAccount(callback);
        }
    }

    @Override
    protected void onActivityResult(final int requestCode, final int resultCode, final Intent data) {
        super.onActivityResult(requestCode, resultCode, data);

        // Required callback.
        loginManager.onActivityResult(requestCode, resultCode, data);
    }

    // Make sure this is static so we don't keep a reference
    // to Context, which can cause memory leaks.
    private static class ExampleLoginCallback implements FirefoxDataLoginManager.LoginCallback {
        @Override
        public void onSuccess(final FirefoxDataClient dataClient) {
            try {
                final List<HistoryRecord> history = dataClient.getAllHistory().getResult();
                for (final HistoryRecord record : history) {
                    Log.d("FxData", record.getTitle() + ": " + record.getURI());
                }
            } catch (final FirefoxDataException e) {
                Log.e("FxData", "failed to get data", e);
            }
        }

        @Override
        public void onFailure(final FirefoxDataException e) {
            Log.e("FxData", "Failed to get DataClient", e);
        }

        @Override
        public void onUserCancel() {
            Log.d("FxData", "User cancelled log-in attempt.");
        }
    }
}

Explanation

Notes on exposed APIs:

• Classes exposed in the org.mozilla.fxa_data.impl package are not intended for public consumption and are subject to change.
• Classes from the thirdparty and gecko modules are exposed due to a known issue and should not be considered public. All public APIs can be found in the org.mozilla.fxa_data package, with the exception of classes in the impl package which is private.

The FirefoxData class is the entry point to the library. It can return a FirefoxDataLoginManager, which we recommend storing a reference to in onCreate:

    private FirefoxDataLoginManager loginManager;

    protected void onCreate(final Bundle savedInstanceState) {
        ...
        loginManager = FirefoxData.getLoginManager(this);

For successful logins, the following must also be called:

    protected void onActivityResult(final int requestCode, final int resultCode, final Intent data) {
        ...
        loginManager.onActivityResult(requestCode, resultCode, data);

The FirefoxDataLoginManager allows you to sign into an account, access a previously signed in account, or sign out of the signed in account. To log in, e.g. when the user clicks a sign in button, you might call:

    public void onClick(View v) {
        loginManager.promptLogin(MainActivity.this, "Your app name", callback);
    }

Firefox Accounts have a dashboard of all synced devices - your app name name is displayed there so the user can identify which device is which.

The FirefoxDataLoginManager.LoginCallback argument requires the following methods:

• onSuccess(FirefoxDataClient): called when the login was completed successfully. The account will be saved for future use: FirefoxDataLoginManager.loadStoredAccount can be used instead of promptLogin so the user doesn't have to log in again and FirefoxDataLoginManager.isSignedIn should now return true.
• onFailure(FirefoxDataException): login (or loading a stored account) has failed: it's probably best to try again later.
• onUserCancel(): called when the user cancelled a login attempt (it should never be called for loadStoredAccount).

Notes:

• These callbacks are called from a background thread which is okay to block
• LoginCallback may leak memory if it stores a reference to the Context so generally avoid using anonymous classes with it!

The FirefoxDataClient given to onSuccess can be used to access the user's data. It includes the following blocking methods (which are okay to call from the callback):

• getAllBookmarks()
• getBookmarksWithLimit(int)
• getAllHistory()
• getHistoryWithLimit(int)
• getAllPasswords()
• getPasswordsWithLimit(int)

The *WithLimit methods can be used to return a subset of a user's data. This can be useful if the user has a lot of data or you're making test queries.

Each method returns a DataCollectionResult<T>, which wraps the returned value (to allow for future API expansion). Call DataCollectionResult.getResult() to return one of:

• BookmarkFolder
• List<HistoryRecord>
• List<PasswordRecord>

History & passwords are largely self-explanatory but for bookmarks, we return the root bookmark folder of a tree-like structure. You can access the actual bookmarks with the following methods:

• List<BookmarkRecord> getBookmarks()
• BookmarkFolder getSubfolders()

You should now have the data you need!

Known issues

• We require importing multiple dependencies, which exposes their APIs. We want this to change to one import and no extra exposed APIs.
• We include some large dependencies: appcompat & httpclientlib
• We only support English at the moment
• We haven't investigated ProGuard configurations yet.
• We'd like to host javadocs

Questions? Feedback?

We'd love to hear from you!

If you have questions or feedback about using this library, you can catch us on Mozilla's IRC in the #mobile channel.

If you've found a bug, we'd love it if you file an issue.

Contributing to the repository

Setting up a build

After cloning, in Android Studio, select "File -> Open". Find your ./FirefoxAccounts-android directory and select the build.gradle file in that root directory. Running the default configuration should run the FirefoxDataInRecyclerViewExampleActivity.

You may also want to add a run configuration for SimpleExampleActivity.

Publishing to bintray

To publish, ensure you have a bintray account with the appropriate permissions, add the following to a ./local.properties file:

bintray.user=<username>
bintray.apikey=<api-key>

Increment the version number in ./gradle.properties & run the following to upload:

./publish.sh

Coding notes

The code is laid out into a few modules:

• download: core module, includes the public API.
• gecko/: dependencies imported from fennec, largerly sync code
• thirdparty/: third-party in-tree dependencies
• example/: examples using the library