The Basics

To let you create native modules, we provide inspector projects for both Android and iOS. These are Android Studio and Xcode projects that include the core library used by Forge, as well as an example module to get you started. This environment can be used as a sandbox to develop and compile your module.

Once you are happy with your module, you can use the Toolkit to upload a compiled version with any additional files (detailed below) to the Trigger.io servers. Once we have this compiled copy of your module, you can add the module to your app through the app's config in the Toolkit.

Downloading the inspector projects

Getting setup to develop native modules is fairly simple, but there are some prerequisites you need to install.

Android

  1. You will need Android Studio setup with the Android SDK, you can find details on how to install this on the Android developer site: http://developer.android.com/sdk/index.html
  2. Create a new local version of the module in the Trigger Toolkit
  3. Download the ForgeInspector project by hitting the update button
  4. ForgeInspector and ForgeModule should have been downloaded to the inspector/an-inspector directory
  5. Open Android Studio and select "Open an Existing Android Studio project"
  6. Navigate to <module dir>/inspector/an-inspector/ and choose the build.gradle file.
  7. After opening the project, the toolbar should have a dropdown with "ForgeInspector" selected and a green "Play" button next to it.

If you click the green "Play" button in the Android Studio toolbar it should compile the project and start the ForgeInspector app on your device or emulator.

iOS

  1. You will need a Mac running OS X
  2. You will need Xcode 4.5 or higher: this is available as a free download in the OS X App Store
  3. Create a new local version of the module in the Trigger Toolkit
  4. Download the ForgeInspector project by hitting the update button
  5. (If you can't see modules in the Toolkit, then contact us at support@trigger.io to get into the native modules beta)
  6. Open this project in Xcode.

At this point you can run the inspector project. It includes an app which lists native methods exposed to JavaScript, and allows you to call them with sample data.

Updating inspector projects

Some modules will need to make changes to the Forge build process, such as including 3rd party frameworks, registering a URL handler or requesting app permissions. In order to do this, additional steps can be included in a module which will be run when the module in used in an app.

When you update your module's build steps or change the platform_version in manifest.json, your inspector project will need to be updated.

The Toolkit will remind you automatically when an update is required, and the code and any resources for your module will be preserved.

Structure of the inspector projects

General

The assets folder contains files loaded into the webview, i.e. HTML/JS/CSS files. You shouldn't need to change any of these files.

  • The assets/forge folder contains a prebuilt all.js which should not need to be modified.
  • The assets/src folder contains a prebuilt Forge app designed for testing modules, allowing you to run API methods from a simple web based GUI within the app. It is not recommended you modify this app, as it is re-generated and overwritten when the Inspector project is updated. Instead, it is better to write tests for your module - see Testing your module.

Android

  • modules must contain a package io.trigger.forge.android.modules.<module> where <module> is the module name you gave at creation time.
  • This package must contain an API.java file which is the API exposed to JavaScript, see API methods.
  • It can also contain an EventListener.java to listen for native events, see Events.
  • An example module is included in io.trigger.forge.android.modules.<module>

Important: On Android you should only need to modify files in src and assets/src directly, any other changes should be done using build steps.

Build Variants

  1. In the lower-left corner of Android Studio there is a tab called "Build Variants". Click it.
  2. You should now have a "Build Variants" panel. Set both ForgeInspector and ForgeModule to "vanillaDebug" or "crosswalkDebug" depending on whether you want to build for the Android WebView or for Crosswalk.

iOS

The iOS inspector project should look something like this:

iOS inspector project

The ForgeModule subproject is used to contain the code and resources for your module, and the ForgeInspector outer-project is the sandbox you can run and test your module in before packaging it up to send to Trigger.io.

  • There is no namespacing in Objective-C, you can create files in any structure you like in the ForgeInspector project.
  • Files to be included in the module build should be in the ForgeModule project and included in the ForgeModule target.
  • modules must include a <module>_API.m file which is the API exposed to JavaScript. See Exposing native APIs to JavaScript.
  • modules can also contain <module>_EventListener.m, to listen for native events, see Handling native events.
  • An example module is included in ForgeModule/<module>_API.m

Important: On iOS you should only add or change files in the ForgeModule project, except for assets/src in the ForgeInspector project, which can be modified to test your module.

Structure of a module

In order to upload a module you must put the files that make up a module, along with a manifest for the module in a particular structure in a folder. To help you get started, the Trigger Toolkit can create an initial module folder and manifest.json for you. To do this, choose "Create new local version" after creating a new module in the Toolkit.

modules take the following structure:

.trigger/                      - Code used by the Toolkit to help develop
                                 your module
module/                        - Parts of module to be uploaded for use
                                 when building
    manifest.json              - Contains the basic properties for your
                                 module
    identity.json              - Contains the module name identitifer
    config_schema.json         - Specify the configuration option your
                                 module requires
    inspector_config.json      - Configuration values to use when running
                                 inspector apps
    android/                   - Folder containing all android related
                                 files
        module.jar             - Built Android code
        build_steps.json       - Android build steps, see native build
                                 steps
        res/                   - Android resource files, see "Including
                                 resources"
            values/
                myvalues.xml
        libs/                  - Android libraries
            mysdk.jar
            arm/
                nativesdk.so
    ios/                       - Folder containing iOS related files
        module.a               - Built iOS module
        build_steps.json       - iOS build steps
        bundles/               - iOS bundles (resources) to include
            mymodule.bundle
            mysdk.bundle
        headers/               - Header files for modules built on top of
                                 this one
            SharedHeaders.h
    javascript/
        module.js              - JavaScript code, usually used to expose
                                 your modules API
    tests/                     - see Testing your module
        automated.js           - Automated tests for your module
        interactive.js         - Tests for your module that require user
                                 interaction
        fixtures/              - Files your tests require to run
            test.png
inspector/                     - Inspector projects used to develop your
                                 module
    an-inspector/              - Android inspector project
    ios-inspector/             - iOS inspector project
    ios-inspector.2012-11-19   - A backup of a previous version of the
                                 iOS inspector

manifest.json

The manifest for a module looks something like:

{
    "description": "Example alert box module",
    "namespace": "alert",
    "version": "1.0",
    "platform_version": "v1.4.26"
}

To update your modules manifest you should use the Manifest tab in the Toolkit.

Note: The platform version for your module does not need to match your app, you only need to update your modules platform version if you require newer module feature, or if the Toolkit prompts you to.

identity.json

In more recent platform versions the name identifier for your module is separated from manifest.json and included in an identity.json, this allows you to not include identity.json in source control for your module, and collaborate with other projects on module development.

Trying your module

An inspector app is included which allows you to view and invoke all available API methods.

To run the inspector app from Xcode, select the ForgeInspector target and an appropriate device or simulator:

iOS ForgeInspector

In Eclipse, select the ForgeInspector project and choose to run it as an Android application.

Android ForgeInspector

Building/packaging your module

Android

To build and export your module to be included in an actual Forge app:

  1. Open a terminal and go to /inspector/an-inspector
  2. Run the following command: gradle updateModule
  3. It will now build release .jar and .aar packages for both Android & Crosswalk variants of the module and automatically copy them to your module/android directory :-)

Note: You can also access this build action from Android Studio if you click on the "Gradle" tab in the top right corner and navigate to: an-inspector (root) => Tasks => other => updateModule

iOS

To build and export your module to be included in an actual Forge app, choose the UniversalForgeModule target and press Run. A file build/module.a should appear in the ForgeInspector folder: save that file as ios/module.a in your module folder.

Expected workflow

  1. Create the API methods your module will expose
  2. Implement the event listeners your module will react to
  3. Use the supplied inspector app to invoked your module's API methods and check the return values
  4. Add JavaScript
  5. Write tests
  6. Specify the configuration your module requires
  7. Upload the module
  8. Use the module and share it with others!