This section provides more specific implementation details for each supported platform.

• Android
• iOS

Android

Package Contents

• docs - Integration guide and installation guide
• android/aar - VMX XTD Android library (vmx-xtd-sdk.aar)
• android/example - Example Java functions (VmxXtdExample.java)

Project Setup

To setup the XTD SDK:

1. Import AAR

   1. Copy the vmx-xtd-sdk.aar from the VMX XTD SDK package into the project’s app/libs.
   2. Include the following to the project’s build.gradle

      	repositories {
      	    flatDir {
      	        dirs 'libs'
      	    }
      	}
      	
      	dependencies {
      	    implementation(name: 'stublib', ext: 'aar')
      	} 
   

2. Configure ProGuard
   The following line MUST be added to the app/proguard-rules.pro which controls the ProGuard configuration for the APK being built.

   -keep class com.verimatrix.stublib.StubLib \{ *; }

The ProGuard configuration guarantees that the Verimatrix XTD SDK interface is preserved in the application APK after compilation. This is essential to ensure that the XTD SDK is integrated into the Verimatrix analytics agent at protection time.

API Overview

The Verimatrix XTD API is a Java interface that allows an app to send and receive messages to/from Verimatrix XTD.The API is accessible with the com.verimatrix.stublib.StubLib class static methods.

Receive XTD SDK Messages

To be able to receive commands and other messages, the app MUST register its own callback function. After registering, the registered callback function will be invoked whenever XTD SDK needs to pass any command and operation response results or errors. It is application responsibility to handle those messages accordingly. The given example is just a simplified demo where the app logs all the received messages.

// Import the VMX XTD SDK
  
import com.verimatrix.stublib.StubLib;

/\*\*

* Receive XTD messages example.
    
  \*/
  public static void registerCallback() \{
      try \{
          StubLib.registerCallback(message -> \{
              // Parse and process messages received from the VMX XTD
              // ...
              Log.i(TAG, "Received message: " + message);
          });
      } catch (StubLib.StubLibException e) \{
          Log.e(TAG, "Error registering callback: " + e.getMessage());
      }
  }

The callback is invoked on the UI thread to allow UI interactions if needed. As a result, care should be taken to not do too much work in the callback.

Send Messages to Verimatrix XTD SDK

To be able to uniquely identify the running instance, the app needs to define and set the VUIT value. The example below contains the basic implementation that sends the provision VUIT command to VMX XTD.

Similarly, other commands can be constructed and sent by using the sendMessage API function.

// Import the XTD SDK
import com.verimatrix.stublib.StubLib;

/** Example of how to use the XTD SDK to provision the VUIT with the security analytics agent */
public class SetVUITExample {

    /** Example method of creating the VUIT payload and provisioning this with the security analytics agent using XTD SDK 
     *
     * @param vuit The VUIT to provision
     */
    public static void provisionVUIT(String vuit) {
    
        /** Create the message payload: {"v": 1, "c" : 6, "p" : {"spuid":"SP::example"}}
        * where:
        * "v" - payload format version (MUST be 1)
        * "c" - payload type (provision VUIT is 6)
        * "p" - additional payload (required for provision VUIT payload)
        * "spuid" - required element for provision VUIT payload
        * "SP::example" - required value for "spuid" element, MUST contain the VUIT value, pre-fixed with "SP::" string literal
        */
        String vuitPayload = "{\"v\": 1,\"c\":6,\"p\":{\"spuid\":\"" + vuit + "\"}}";

        try {
          StubLib.sendMessage(vuitPayload);
          } catch (StubLib.StubLibException e) {
          Log.e(TAG, "Error registering callback: " + e.getMessage());
        }
    }

}

iOS

Package Contents

• docs - Integration guide and installation guide
• ios/inc - VMX XTD library include file
• ios/lib - VMX XTD library static library files (for device and simulator)
• ios/example - Example swift functions

Project Setup

1. Copy the contents of the ios/inc and ios/lib folders to your project. Update the USER_HEADER_SEARCH_PATHS and the LIBRARY_SEARCH_PATHS in your project's .xcconfig file accordingly.
2. Link the Verimatrix XTD static library (libvmx-xtd-sdk.a) to your project. Also update the value of OTHER_LDFLAGS in your project's .xcconfig file accordingly.
   • Note: A simulator version (libvmx-xtd-sdk-sim.a) is also provided for convenience during the development phase.
3. Include the header vmx-xtd-sdk.h in your Objective C or Swift project.
   • Note: For Swift projects the vmx-xtd-sdk.h header must be put in your project's bridging header.
4. Refer to the file ios/example/StublibIntegrationExample.swift for example functions on how to use the VMX XTD API.

Example .xcconfig section:

...
// Search paths for headers and libraries
USER\_HEADER\_SEARCH\_PATHS = $(inherited) $SRCROOT/../inc
LIBRARY\_SEARCH\_PATHS = $(inherited) $SRCROOT/../lib

// Verimatrix XTD SDK filenames (static libs, ending with .a)
VMX\_XTD\_STATIC\_LIB\[sdk=iphoneos\*] = vmx-xtd-sdk
VMX\_XTD\_STATIC\_LIB\[sdk=iphonesimulator\*] = vmx-xtd-sdk-sim

// Other Linker Flags
OTHER\_LDFLAGS = $(inherited) -ObjC -l$(VMX\_XTD\_STATIC\_LIB)
...

API Overview

The Verimatrix XTD API provides a few simple Objective C methods in vmx-xtd-sdk.h for keeping compatibility with both Swift and Objective C projects:

// Registers a callback for receiving messages from the XTD system
(void) registerCallback:(XTDStubLibCallback) callback

// Sends a command to the server XTD ARC server
(BOOL) sendMessage:(NSString *) messageJSON
             error:(out NSError **) outError;

// Sets the VUIT value for the running instance
// Note: This API is deprecated, use the sendMessage() function to set the VUIT (previously called SPUID).
(BOOL) setSPUID:(NSString *) spuidJSON
          error:(out NSError **) outError;

Note

• Swift translates the above "BOOL return code with NSError** error" pattern to exceptions, therefore it's advised to use a do/try/catch block when calling the XTD library methods from Swift code. The returned error will be in a generic variable named error after catching errors.
• Verimatrix provides the JSON schema of messages in this integration guide, including the available commands with parameters.

API Usage Examples in Swift

Registering Message Callback

// Example callback function to receive commands from the XTD ARC server in JSON format
let cbFunc: XTDStubLibCallback = {(messageJSON: Optional<UnsafePointer<CChar>>) -> () in

    let messageFromXTD = String(cString: UnsafePointer<CChar>(messageJSON!))
}

// Register a callback function in the XTD library for receiving commands in JSON format from the XTD ARC server
func registerCallback()
{
    XTDStubLib.registerCallback(cbFunc)
}

Provisioning VUIT

/** Example method of creating the VUIT payload and provisioning this with the security analytics agent using XTD SDK 
  *
  * @param vuit The VUIT to provision
  */
func provisionVUIT(_ vuit: String) {
    // Create the message payload {"v": 1, "c" : 6, "p" : {"spuid":"SP::example"}}
    let vuitPayload = "{\"v\": 1,\"c\":6,\"p\":{\"spuid\":\"\(vuit)\"}}";  
    do {
        try XTDStubLib.sendMessage(vuitPayload)
    } catch {
        // Send message failed
        print("XTD stub lib error: \(error)")
    }
}