Changing build configuration

modules often need to change properties of the app which cannot be set at runtime, such as app permissions on Android, or linked system frameworks on iOS. These changes can be described in the native build steps file for each platform, and will be applied at build time for the Forge app.

The build steps go in either android/build_steps.json or ios/build_steps.json in the module's folder. These JSON files take the following format:

[
    {
        "do": {
            "build_task": {
                "parameter": "value"
            }
        }
    }, {
        "do": {
            "second_build_task": {
                "input": "data",
                "other_input": "data2"
            }
        }
    }
]

This consists of an array of tasks to perform before the build is completed.

The types of task that can be performed and the parameters that need to be passed to each task varies by platform and is described below.

Note: After changing the build steps for either Android or iOS it is important to update the inspector project, any new build steps will be applied to the project to keep your development environment as close as possible to the final Forge build.

Android

android_add_permission

  • permission: the permission to add, i.e. android.permission.CAMERA

Example:

{
    "do": {
        "android_add_permission": {
            "permission": "android.permission.CAMERA"
        }
    }
}

android_add_feature

  • feature: the feature to request
  • required: Whether or not the feature is required, "true" or "false"

Example:

{
    "do": {
        "android_add_feature": {
            "feature": "android.hardware.camera",
            "required": "true"
        }
    }
}

android_add_to_manifest

This is a flexible helper step which can be used to add various xml elements to the root of AndroidManifest.xml.

  • element: A json representation of the xml element to add

Example:

Add a custom permission:

{
    "do": {
        "android_add_to_manifest": {
            "element": {
                "tag": "permission",
                "attributes": {
                    "android:name": "com.example.sdk.permission.C2D_MESSAGE",
                    "android:protectionLevel": "signature"
                }
            }
        }
    }
}

android_add_to_application_manifest

This is a flexible helper step which can be used to add various xml elements to the application section of AndroidManifest.xml.

  • element: A json representation of the xml element to add

Examples:

Adding an activity:

{
    "do": {
        "android_add_to_application_manifest": {
            "element": {
                "tag": "activity",
                "attributes": {
                    "android:name": "com.example.sdk.MyActivity"
                    "android:screenOrientation": "portrait"
                }
            }
        }
    }
}

Adding a service:

{
    "do": {
        "android_add_to_application_manifest": {
            "element": {
                "tag": "service",
                "attributes": {
                    "android:name": "com.example.sdk.MyService"
                }
            }
        }
    }
}

Adding a receiver:

{
    "do": {
        "android_add_to_application_manifest": {
            "element": {
                "tag": "receiver",
                "attributes": {
                    "android:name": "com.example.sdk.MyReceiver"
                },
                "children": [{
                    "tag": "intent-filter",
                    "children": [{
                        "tag": "action",
                        "attributes": {
                            "android:name": "android.intent.action.BOOT_COMPLETED"
                        }
                    }]
                }]
            }
        }
    }
}

android_add_to_application_manifest_attributes

This is a flexible helper step which can be used to add various xml attributes to the activity section of AndroidManifest.xml.

  • attributes: A json representation of the xml attributes to add

android_add_to_activity_manifest

This is a flexible helper step which can be used to add various xml elements to the activity section of AndroidManifest.xml.

  • element: A json representation of the xml element to add

android_add_to_activity_manifest_attributes

This is a flexible helper step which can be used to add various xml attributes to the activity section of AndroidManifest.xml.

  • attributes: A json representation of the xml attributes to add

Example:

{
    "do": {
        "android_add_to_activity_manifest_attributes": {
            "attributes": {
                "android:windowSoftInputMode": "adjustResize"
            }
        }
    }
}

android_add_proguard_rule

If you use reflection in your module, you may need to disable ProGuard obfuscation for some classes. Use this task to configure these ProGuard rules.

For information about ProGuard configuration, see its manual.

Example:

Preserve code in the com.example namespace:

{
    "do": {
        "android_add_proguard_rule": {
            "rule": "-keep class com.example.** { *; }"
        }
    }
}

android_add_gradle_dependency

This step allows you to add external Gradle dependencies to your module.

The syntax supports Maven classifiers, for more information see section "24.4.1.3 Classifiers" in the Gradle dependency management documentation.

Example:

Add v4.3.23 of the Google Play Services library to your module:

{
    "do": {
        "android_add_gradle_dependency": "com.google.android.gms:play-services:4.3.23"
    }
}

android_add_gradle_exclude_jar

This step allows you to exclude jar files used by other modules that cause conflicts with your module.

Example:

The Facebook SDK relies on an outdated version of the Bolts library that conflicts with the newer version used by the Parse SDK:

{
    "do": {
        "android_add_gradle_exclude_jar": "bolts-android-1.1.2.jar"
    }
}

iOS

add_ios_system_framework

  • framework: the framework to add

Example:

{
    "do": {
        "add_ios_system_framework": {
            "framework": "CoreMedia.framework"
        }
    }
}

ios_add_url_handler

  • scheme: URL scheme to handle

Example:

{
    "do": {
        "ios_add_url_handler": {
            "scheme": "myurlscheme"
        }
    }
}

ios_add_background_mode

  • mode: one of the background modes which Apple enumerates in UIBackgroundModes of the Information Property List Key Reference

Example:

{
    "do": {
        "ios_add_background_mode": {
            "mode": "audio"
        }
    }
}

set_in_info_plist

  • key: Key to add/change: you can use a.b to change key b nested inside a
  • value: Value to set it to

Example:

{
    "do": {
        "set_in_info_plist": {
            "key": "MyKey",
            "value": "My Data"
        }
    }
}

ios_configure_ats

  • entries: Array of iOS App Transport Security configuration entries.

For full documentation on available keys see Apple's NSAppTransportSecurity documentation.

Example:

[
    {
        "domain": "httpbin.org",
        "NSThirdPartyExceptionAllowsInsecureHTTPLoads": true
    },
    {
        "domain": "my.domain.com",
        "NSExceptionRequiresForwardSecrecy": false,
        "NSExceptionMinimumTLSVersion": "TLSv1.0"
    }
]

ios_add_i8n_plist

This step allows you to add internationalization entries for strings in the App's Info.plist file.

Example:

[
       { "do": { "ios_add_i8n_plist": {
           "lang": "de",
           "key": "CFBundleDisplayName",
           "string": "Zungenbrecher"
       } } },
       { "do": { "ios_add_i8n_plist": {
           "lang": "de",
           "key": "NSCalendarsUsageDescription",
           "string": "Blaukraut bleibt Blaukraut und Brautkleid bleibt Brautkleid."
       } } },

       { "do": { "ios_add_i8n_plist": {
           "lang": "fr",
           "key": "CFBundleDisplayName",
           "string": "Phrase difficile à prononcer"
       } } },
       { "do": { "ios_add_i8n_plist": {
           "lang": "fr",
           "key": "NSCalendarsUsageDescription",
           "string": "Ces cerises sont si sûres qu'on ne sait pas si c'en sont."
       } } }
]