Android Extension Library¶

This document guides developers on how to install, configure, and use the Android Commerce Extension Library. This library provides a set of tools and Capacitor plugins to extend the core functionality of the Commerce application.

Initial Project Setup¶

To extend the library, your project should follow a standard Android/Capacitor structure. The following example highlights the key files you will be modifying.

Example File Structure¶

Capacitor files (like capacitor.config.json) are typically generated by running npx cap sync.

.
├── android
│ ├── app
│ │ ├── build.gradle
│ │ ├── capacitor.build.gradle
│ │ └── src
│ │     ├── main
│ │     │ ├── AndroidManifest.xml
│ │     │ ├── assets
│ │     │ │ ├── capacitor.config.json
│ │     │ │ ├── capacitor.plugins.json
│ │     │ │ └── public
│ │     │ ├── java
│ │     │ │ └── org
│ │     │ │     └── jumpmind
│ │     │ │         └── posv2
│ │     │ │                 └── MainActivity.java
│ │     │ └── res
│ │     │     ├── values
│ │     │     │ └── styles.xml
│ │     │     └── xml
│ │     │         └── config.xml
│ │     └── test
│ │         ├── java
│ │         └── resources
│ ├── build.gradle
│ ├── capacitor-cordova-android-plugins
│ ├── capacitor.settings.gradle
│ ├── gradle
│ │ └── wrapper
│ │     ├── gradle-wrapper.jar
│ │     └── gradle-wrapper.properties
│ ├── gradle.properties
│ ├── gradlew
│ ├── gradlew.bat
│ ├── local.properties
│ ├── settings.gradle
│ └── variables.gradle
├── build.gradle
├── capacitor.config.json
├── java.gradle
├── local.properties
├── package-lock.json
└── package.json

Customizing App Theme¶

To ensure your application's theme inherits from the core Commerce theme, create or modify res/values/styles.xml and add the following:

These styles extend the base Commerce themes. You can add your own tags within these styles to override or add custom attributes.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <style name="AppTheme" parent="JmcBaseTheme">
        <!-- Example: Override the primary color. (Ensure @color/my_primary_color is defined in a colors.xml file) -->
        <!-- <item name="colorPrimary">@color/my_primary_color</item> -->

        <!-- Example: Override a specific text appearance -->
        <!-- <item name="android:textColor">@color/my_custom_text_color</item>
             <item name="android:textSize">22sp</item> -->
    </style>
    <style name="AppTheme.NoActionBar" parent="JmcBaseTheme.NoActionBar">
        <!-- Example: Set the status bar color -->
        <!-- <item name="android:statusBarColor">@color/my_primary_color</item> -->
    </style>
    <style name="AppTheme.NoActionBarLaunch" parent="JmcBaseTheme.NoActionBarLaunch">
        <!-- Example: Set the window background to your splash screen drawable -->
        <!-- <item name="android:windowBackground">@drawable/my_splash_screen</item> -->

        <!-- Example: You can also set the status bar color here to match the splash screen -->
        <!-- <item name="android:statusBarColor">@color/my_splash_background_color</item> -->
    </style>
</resources>

Installation and Configuration¶

Follow these steps to add the library and configure your build.gradle file at the app level.

Add library dependencies¶

Add the following line to the dependencies block into your build file. Ensure you define $commerceVersion within the same file or within variables.gradle.

dependencies {
    // ... other dependencies
    implementation 'org.jumpmind.android:library:$commerceVersion'
}

Configure Build Variables¶

Add the following resValue lines inside the android.defaultConfig block. This will be used Capacitor.

android {
    // ...
    defaultConfig {
        applicationId "[your.package.name]"
        // ...

        // These values are required by the Capacitor library
        // to identify your app's package and URL scheme.
        resValue "string", "package_name", applicationId
        resValue "string", "custom_url_scheme", applicationId
    }
    // ...
}

Commerce Activity Manager¶

The CommerceActivityManager is a helper class that simplifies the initialization of the library's plugins and UI. You should use it inside your main BridgeActivity (typically MainActivity.java).

The manager provides two key methods: - registerPlugins(): Registers all required core Commerce plugins with the Capacitor bridge. - setupUI(): Initializes and configures base UI configurations required by the Commerce library.

Example implementation:

import com.getcapacitor.BridgeActivity;

import org.jumpmind.android.library.CommerceActivityManager;

public class MainActivity extends BridgeActivity {
    private final CommerceActivityManager manager = new CommerceActivityManager(this);

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        manager.registerPlugins();
        manager.setupUI();

        super.onCreate(savedInstanceState);
    }
}

Peer dependencies¶

Our library relies on two key peer dependencies that are not bundled with it. You must provide these in your project.

Capacitor¶

Our library is built on Capacitor and expects your host application to be a Capacitor project. You are responsible for managing your project's Capacitor installation and configuration.

For setup instructions, see the official Capacitor Android documentation.

AESDK (Aurus Payments)¶

The Aurus (AESDK) payment library is only required for clients using an Aurus payment integration.

This library is not public. Please contact your Aurus representative to obtain the required .aar file. Once you have the file, add it to your Android project. From there, you can register our capacitor plugin JmcAesdkPlugin to fully integrate with our Commerce server.

Signing APK¶

To create a release-ready, signed APK, you must sign it with a keystore file.

Generating a Keystore File¶

If you don't have a keystore file, you can generate one using Android Studio: 1. Open your project in Android Studio. 2. Navigate to Build > Generate Signed Bundle / APK.... 3. Select APK and click Next. 4. Below the "Key store path" field, click Create new.... 5. Fill out the form: - Key store path: Choose a location to save your file (e.g., my-release-key.keystore). - Provide and confirm a secure password for the keystore. - Key alias: Give your key a name (e.g., release_key). - Provide and confirm a secure password for the key (this can be the same as the keystore password). 6. Click OK to generate the file.

Releasing¶

Most CI/CD platforms (like Appflow, Jenkins, etc.) have tasks that can build a signed APK. You will need to provide this keystore file and its credentials (passwords, alias) to the build task.