Migrating from previous iOS agent versions

Changes introduced with AppMon 2018 October

1. Deprecated old startup API - New Universal startup API available

The old manual startup API:

  • startupWithApplicationName:serverURL:allowAnyCert:certificatePath
+ (DTX_StatusCode) startupWithApplicationName:(NSString *)applicationId
                                      serverURL:(NSString *)serverURL
                                   allowAnyCert:(BOOL)allowAnyCert
                                certificatePath:(NSString *)pathToCertificateAsDER

Has been deprecated and completely removed. We have introduced and new and more versatile startup API. The new API takes a configuration dictionary, and starts the Mobile Agent with supplied configuration.

Method signature

  • startupWithConfig:(NSDictionary <NSString*,id>*) config;
+ (DTX_StatusCode)startupWithConfig:(NONNULL NSDictionary<NSString*,id>*)config;

yy

  • Configuration dictionary

The configuration dictionary is a key-value dictionary where the Keys correspond to the keys you can use in your Info.plist, but with a "k" prefix. For example, DTXLogLevel => kDTXLogLevel. The Info.plist keys themselves are not changed. You can check the full list of available keys in the Intrsumentation keys section of the iOS auto instrumentation page.

2. Removed JSBridge

The JavaScript bridge—which has been deprecated in AppMon 2018 April—is now fully removed. To manually instrument JavaScript, use the JavaScript ADK instead.

3. Removal of Authentication delegate (NSURLConnection)

We have completely migrated to using NSURLSession instead of NSURLConnection. Which means we no longer support the authentication delegate. Use the new certificate pinning feature instead.

4. DTXMonitorCookie has been removed.

  • Both the plist setting and the API have been removed.
  • Use the new beaconHeaders call instead
let beaconHeaders = [
        "App":"My app",
        "Platform":"iOS",
        "Vendor":"Dynatrace"
        ]
Dynatrace.setBeaconHeaders(beaconHeaders)

5. Misc Changes

  • Update your Podfile if you are using CocoaPods:
    If you use the Dynatrace Framework:

    use_frameworks!
    pod 'Dynatrace', '~> 7.2'
    

    If you use the Dynatrace static library:

    pod 'Dynatrace/lib', '~> 7.2'
    
  • Kony is no longer supported.

  • Some instrumentation keys have been merged.

    • DTXInstrumentWebRequestTagging and DTXInstrumentWebRequestTiming are no longer separate features. Use only DTXInstrumentWebRequestTiming.
    • DTXInstrumentWebViewTagging and DTXInstrumentWebViewTiming are also no longer separate features. Use only DTXInstrumentWebViewTiming.
    • Setting DTXInstrumentWebRequestActionWrapping has been completely removed.
    • DTXURLFilters implementation has been stripped down and simplified.
    <key>DTXURLFilters</key>
        <array>
            <dict>
                <key>Url Name</key>
                <string>example.com</string>
            </dict>
            <dict>
                <key>Url Name</key>
                <!-- URL regex is also allowed -->
                <string>example.(com|org)</string>
            </dict>
        <array>
    
    

Changes introduced with AppMon 2018 April

Update your Podfile if you are using CocoaPods:

If you use the Dynatrace Framework:

use_frameworks!
pod 'Dynatrace', '~> 7.1'

If you use the Dynatrace static library:

pod 'Dynatrace/lib', '~> 7.1'
  • Setting DTXHybridApplication needs to be set to true for hybrid applications that also use a JavaScript agent.
  • Setting DTXInstrumentWebRequestActionWrapping has become deprecated.
  • Method setMonitorCookie has become deprecated, use setBeaconHeaders instead.
  • JavaScript Bridge (Dynatrace.js) is deprecated, use the JavaScript ADK instead.

Changes introduced with AppMon 2017 May

  • Update your Podfile if you are using CocoaPods:

If you use the Dynatrace Framework:

use_frameworks!
pod 'Dynatrace', '~> 7.0'

If you use the Dynatrace static library:

pod 'Dynatrace/lib', '~> 7.0'
  • Setting DTXApplicationID has become mandatory.

Changes introduced with AppMon 6.5

The migration steps for AppMon 6.5 are based on an AppMon 6.2 or 6.3 setup.

Replace libDynatraceUEM.a with libDynatrace.a or dynatrace.framework

  1. Add thelibDynatrace.a or Dynatrace.framework file to your project where the libDynatraceUEM.a file currently resides.
  2. Update any library or framework path references from libDynatraceUEM.a to libDynatrace.a or Dynatrace.framework.
  3. If you use the framework add it to the embedded frameworks of your Xcode project.
  4. Remove the old libDynatraceUEM.a file from your project.

Search and replace

  • Prefix of status code return value of manual instrumentation methods changed from CPWR_ to DTX_
  • Update CPWR_Uem/CPWR_UemOff to DTX_CaptureOn/DTX_CaptureOff
  • Update any reference of DynatraceUEM to Dynatrace
  • Update any reference of UEMAction to DTXAction
  • Update any reference of UEMWebRequestTiming to DTXWebRequestTiming

Manual instrumentation

Already deprecated support for manual lifecycle Instrumentation was removed. If manual lifecycle instrumentation classes are still used as base class, replace them with their UI<...>Controller equivalent:

  • Update CompuwareUEMViewController to UIViewController
  • Update CompuwareUEMNavigationController  to UINavigationController
  • Update CompuwareUEMPageViewController  to UIPageViewController
  • Update CompuwareUEMReferenceLibraryViewController  to UIReferenceLibraryViewController
  • Update CompuwareUEMSplitViewController  to UISplitViewController
  • Update CompuwareUEMTabBarController  to UITabBarController
  • Update CompuwareUEMTableViewController  to UITableViewController

Auto-instrumentation

The auto-instrumentation settings keys used in the Info.plist file have changed. The new keys can be found Auto-Instrumentation for iOS.

JavaScript bridge

  • ReplaceCompuwareUEM.js with now Dynatrace.js

Xcode Plugin

As of Xcode 8 the AppMon Xcode Plugin is no longer supported. For security reasons, Apple discontinued Plugin support in Xcode and moved to Source Code Editor Extensions. However, Source Code Editor Extensions can only modify source code and cannot implement new functionality that is required for the AppMon plugin.

Changes introduced with AppMon 6.2

AppMon 6.2 and later includes a renaming from Compuware back to the original Dynatrace. If you are currently using a version of the iOS ADK prior to AppMon 6.2, replace the existing library and header files with the new ones.

Replace libCompuware.a with libDynatraceUEM.a

  1. Add the libDynatraceUEM.a file to your project where the libCompuwareUEM.a file currently resides.
  2. Update any library path references from libCompuwareUEM.a to libDynatraceUEM.a.
  3. Remove the old libCompuwareUEM.a file from your project.

Handling deprecated classes

File names have changed to reflect rebranding. The change has minimum impact and you can simply replace the old file with the new. However the compiler issues notices that CompuwareUEM classes have been deprecated. Your project continues to build and run as it did before. It is recommended that you eventually update your code to use the new class names, since the deprecated classes are eventually removed.

  1. Update any reference of CompuwareUEM.h to DynatraceUEM.h.
  2. Update any reference of [CompuwareUEM method] to [DynatraceUEM method].

Versions earlier than AppMon 5.6

In releases earlier than AppMon 5.6, special characters such as spaces in System Profile - Error Detection conditions were automatically replaced with underscores by the Mobile Agent. Be sure you have the right comparison strings, because the Mobile Agent for AppMon 5.6 and later does not replace the strings.