Dynatrace Fastlane plugin

Getting Started

This project is a fastlane plugin. To get started with fastlane-plugin-dynatrace, add it to your project by running:

fastlane add_plugin dynatrace

Dynatrace Managed

If the installation is on version 1.195 or earlier the Symbolication Client has to be manually download and specified (dtxDssClientPath), else it's fetched and updated automatically. A matching version can be downloaded manually with this link https://api.mobileagent.downloads.dynatrace.com/sprint-latest-dss-client/xyz by replacing xyz with the 3-digit sprint version of your Dynatrace Managed installation.

About the Dynatrace fastlane plugin

This plugin allows you to decode and upload symbol files (iOS) or just upload obfuscation mapping files (Android) to Dynatrace. You can also use it to first download your latest dSYM files from App Store Connect if you use Bitcode.

Action: `dynatrace_process_symbols`

Supported Platforms	ios, android

Is your app Bitcode enabled?

Only applies for apps distributed via the AppStore or TestFlight.

If your app is bitcode enabled, then the dSYMs that are generated during the Xcode build are not the dSYMs you want to upload to Dynatrace. This is because Apple recompiles the application on their servers, generating new dSYM files in the process. These newly generated dSYM files need to be downloaded from App Store Connect, then processed and uploaded to Dynatrace.

Important

There is a time gap between the application being uploaded to App Store Connect and the dSYM files to be ready. So we have to introduce some "wait" time in the CI to accomodate for this. You can do this by setting the waitForDsymProcessing to true. Unfortunately, Apple does not specify how long this time is. We recommend 1800 seconds (30 mins) as this is usually enough for the symbols are ready for download. You can increase this timeout if needed (waitForDsymProcessingTimeout).

Notice that this timeout is only the maximum waiting time. If the symbol files are ready sooner, it will continue processing and will not wait for the whole duration of the timeout.

Automatically downloading dSYMs and using AppFile for authentication

AppFile

app_identifier("com.yourcompany.yourappID") # bundle identifier of your app
apple_id("[email protected]")

Fastfile

dynatrace_process_symbols(
    appId: "<Dynatrace application ID>",
    apitoken: "<Dynatrace API token>",
    os: "ios",
    bundleId: "<CFBundlebundleId (iOS) / package (Android)>",
    versionStr: "<Build Number (CFBundleVersion)>",
    version: "<App Version (CFBundleShortVersionString)>",
    server: "<Dynatrace Environment URL>",
    downloadDsyms: true
)

If you are NOT using Bitcode, or if you have already downloaded your new symbols from App Store Connect manually.

Supply all parameters locally

dynatrace_process_symbols(
    appId: "<Dynatrace application ID>",
    apitoken: "<Dynatrace API Token>",
    os: "<ios> or <android>",
    bundleId: "<CFBundlebundleId (iOS) / package (Android)>",
    versionStr: "<CFBundleShortVersionString (iOS) / versionName (Android)>",
    version: "<CFBundleVersion (iOS) / versionCode (Android)>",
    server: "<Dynatrace Environment URL>",
    symbolsfile: "<Symbols File Path>"
)

List of all Parameters

Key	Description	default value
action	(iOS only) Action to be performed by DTXDssClient (`upload` or `decode`).	`upload`
downloadDsyms	(iOS only) Download the dSYMs from App Store Connect.	`false`
waitForDsymProcessing	(iOS only) Wait for dSYM processing to be finished.	`true`
waitForDsymProcessingTimeout	(iOS only) Timeout in seconds to wait for the dSYMs be downloadable.	`1800`
username	(iOS only) The username/AppleID to use to download the dSYMs. Alternatively you can specify this in your AppFile as `apple_id`.
os	The type of the symbol files, either `ios` or `android`.
apitoken	Dynatrace API token with mobile symbolication permissions.
dtxDssClientPath	(DEPRECATED) The path to your DTXDssClient. The DTXDssClient is downloaded and updated automatically, unless this key is set.
appID	The application ID you get from your Dynatrace environment.
bundleId	The CFBundlebundleId (iOS) / package (Android) of the application. Alternatively you can specify this in your AppFile as `app_identifier`.
versionStr	The CFBundleShortVersionString (iOS) / versionName (Android)
version	The CFBundleVersion (iOS) / versionCode (Android). Is also used for the dSYM download.
symbolsfile	Path to the dSYM file to be processed. If downloadDsyms is set, this is only a fallback.
server	The API endpoint for the Dynatrace environment (e.g. `https://environmentID.live.dynatrace.com` or `https://dynatrace-managed.com/e/environmentID`).
debugMode	Enable debug logging.	false

AppStore Connect Two-Factor-Authentication

When the plugin is used to download symbols from AppStore Connect automatically (downloadDsyms: true) valid login credentials to an account with permissions to access the dSYM files are required. The preferred method of doing so is by setting the FASTLANE_USER and FASTLANE_PASSWORD environment variables to their respective values.

Apple announced that 2-Factor-Authentication for the AppStore Connect API will be enforced starting February 2021. This limits the ability to automate the symbol processing, because it will most likely involve manual interaction, which is not suitable for CI automation. The only workaround at this point in time is to pre-generate a session and cache it in CI.

Fastlane Session

The full documentation for this can be found on the fastlane docs under spaceauth.

You can generate a session by running fastlane spaceauth -u [email protected] on your machine and copy the output into an environment variable FASTLANE_SESSION on the target system (e.g. CI).

NOTE

Session is only valid in the "region" you create it. If you CI is in a different geographical location the authentication might fail.
Generated sessions are valid up to one month. Apple's API doesn't specify details about that, so it will only be visible by a failing build.

Example

Try it by cloning the repo, running fastlane install_plugins and bundle exec fastlane test.

Issues and Feedback

For any other issues and feedback about this plugin, please submit it to this repository or contact Dynatrace Support.

Troubleshooting

If you have trouble using plugins, check out the Plugins Troubleshooting guide.

Using fastlane Plugins

For more information about how the fastlane plugin system works, check out the Plugins documentation.

About fastlane

fastlane is the easiest way to automate beta deployments and releases for your iOS and Android apps. To learn more, check out fastlane.tools.