Qualtrics React Native Mobile SDK

https://www.npmjs.com/package/react-native-qualtrics

QualtricsSIReactNative contains components used to provide a packaged npm module of the Qualtrics' mobile SDK that users can install into mobile applications built using React Native.

Refer this wiki for instructions on getting started with react-native-qualtrics. Refer Troubleshooting for common errors.

Components

1. react-native-qualtrics: TypeScript npm module wrapper that is used to access native mobile SDKs. This is the npm module users install and this is where the public API functions used in a React Native app are defined. Contains the React Native Bridging modules used to call functions defined in Qualtrics' native mobile SDKs (iOS and Android).
2. RNQualtricsDigitalExample: A React Native mobile application that tests using the Qualtrics' mobile SDK by importing react-native-qualtrics.

The library setup was created with react-native-builder-bob using npx create-react-native-library@latest RNQualtricsDigital command.

Development Set Up

The SDK and test app is written in ReactNative using Typescript.

IDE setup

Recommended IDEs are IntelliJ Ultimate or VSCode. There are some additional file templates and styling rules applied for IntelliJ, so if you're familiar with using it, it's preferred.

Install IntelliJ Idea or VSCode

Environment setup

Compiling app for iOS and Android requires platform-specific tools:

• Install XCode and run it at least once to install additional iOS platform tools
• Install additional iOS simulators required (XC->Preferences...->Components)
• Install Android Studio and Android SDK
• Configure AVD in the Android Studio
• Install Java 11. We recommend using a tool called Sdk Man. Remember to properly set JAVA_HOME variable in your shell.

Tooling installation

You will also need brew, nvm, cocoapods, yarn, watchman and react-native tools:

• Brew is an application installer for OSX, install it from here
• NVM helps maintain node.js versions. You can install it from here
• Yarn is a package manager. You can install it using:

brew install yarn

• Watchman allows to track changes in the filesystem and is used by RN bundler. You can install it using:

brew install watchman

• Cocoapods is an iOS package manager. Install it using:

brew install cocoapods

• Make sure you have react-native CLI installed. Run:

  react-native

  If react-native is not installed, install it globally:

  First make sure to run

  nvm use

  then run:

  npm install -g react-native-cli

Running the app

Tested using: [[email protected] && [email protected] [email protected]] To switch node/npm versions, run nvm use (don't have nvm? instructions here)

Basic setup

To get started with the project, run yarn in the root directory to install the required dependencies for each package:

yarn

While it's possible to use npm, the tooling is built around yarn, so you'll have an easier time if you use yarn for development.

While developing, you can run the example app to test your changes. Any changes you make in your library's JavaScript code will be reflected in the example app without a rebuild. If you change any native code, then you'll need to rebuild the example app.

To start the packager:

yarn example start

To run the example app on Android:

yarn example android

To run the example app on iOS:

yarn example ios

RN New Architecture

By default, the example is configured to build with the old architecture. To run the example with the new architecture, you can do the following:

1. For Android, run:

   ORG_GRADLE_PROJECT_newArchEnabled=true yarn example android

2. For iOS, run:

   RCT_NEW_ARCH_ENABLED=1 yarn example pods
   yarn example ios

Note: New architecture is currently not supported by this library. This command will fail.

If you are building for a different architecture than your previous build, make sure to remove the build folders first. You can run the following command to cleanup all build folders:

yarn clean

To confirm that the app is running with the new architecture, you can check the Metro logs for a message like this:

Running "RNQualtricsDigitalExample" with {"fabric":true,"initialProps":{"concurrentRoot":true},"rootTag":1}

Note the "fabric":true and "concurrentRoot":true properties.

Development

Lint

Make sure your code passes TypeScript and ESLint. Run the following to verify:

yarn typecheck
yarn lint

To fix formatting errors, run the following:

yarn lint --fix

Unit tests

Test for js part of this library are located in src/__tests__

Run the unit tests by:

yarn test

Making changes to RN Bridge files

To edit the Objective-C or Swift files, open example/ios/RNQualtricsDigitalExample.xcworkspace in XCode and find the source files at Pods > Development Pods > react-native-qualtrics.

To edit the Kotlin files, open example/android in Android studio and find the source files at react-native-qualtrics under Android.

Making changes to RNQualtricsDigitalExample

All changes in App.tsx only need an app reload.

Reload the app:

1. (on iOS simulator) Use the shake gesture (or ⌘+D keyboard shortcut, when on a simulator), tap "Reload".
2. (on Android emulator) Tap R twice

Sometimes it may be required to reset React Native cache as well:

react-native start --reset-cache

Scripts

The package.json file contains various scripts for common tasks:

• yarn bootstrap: setup project by installing all dependencies and pods.
• yarn typecheck: type-check files with TypeScript.
• yarn lint: lint files with ESLint.
• yarn test: run unit tests with Jest.
• yarn example start: start the Metro server for the example app.
• yarn example android: run the example app on Android.
• yarn example ios: run the example app on iOS.

Running the App with Native Module from branch

Note: Not tested after migration to React Native 0.72

Testing RNTestApp with Android branch

1. Run the AndroidSDK-Publish-dev Jenkins Build with the branch in QualtricsSI that you want to test with. Make sure to update the version number in build.gradle on the branch being built.
2. Open test/RNTestApp folder
3. In build.gradle (Module: app), change the maven url to https://s3-us-west-2.amazonaws.com/si-mobile-sdks/dev/android/
4. Do the same as in step 2 and change the maven url in build.gradle (Module: react-native-qualtrics) AND update the com.qualtrics:digital dependency to point to the right version number. If using v1.4 in dev S3 bucket, it should be compile 'com.qualtrics:digital:1.4'.
5. Run rm -rf ~/.gradle/caches to remove all cached dependencies
6. react-native run-android or run the app in Android Studio
7. Change both maven urls back to https://s3-us-west-2.amazonaws.com/si-mobile-sdks/android/ when you do not want to test RNTestApp against the build of the SDK in S3 anymore

Testing RNTestApp with iOS branch

Follow instructions here to upload a dev SDK to a private CocoaPods repo and pod install the uploaded dev SDK: https://gitlab-app.eng.qops.net/site-intercept/mobile/qualtrics-pod-specs/blob/master/README.md#qualtrics-dev-cocoapod

Refer this wiki for instructions on getting started with react-native-qualtrics. Refer Troubleshooting for common errors.

Qualtrics App Feedback React Native API Reference

All function parameters require specific types for the native mobile SDKs to work even though the API is written in JavaScript for React Native. Any parameter type will be accepted as function parameters, but the API functions will fail silently without the correct specified parameter types in the API documentation.

function initialize(brandid, projectid, interceptid, callback)

initializes Qualtrics singleton with specified params

@parameters brandid (string) - intercept brand id projectid (string) - intercept project id interceptid (string) - intercept id callback (function) - optional method called if defined

@return InitializationResult (object) - returned in callback, see InitializationResult for more info

Use case example - initialize library in ex. App component componentDidMount method without callback:

import Qualtrics from 'react-native-qualtrics';

...
class App extends Component {
  componentDidMount () {
    Qualtrics.initialize('BRAND ID', 'PROJECT ID', 'INTERCEPT ID');
  }
}
...

Replace BRAND ID, PROJECT ID, and INTERCEPT ID with the intercept ID you obtained earlier.

Initialize method with callback:

import Qualtrics from 'react-native-qualtrics';

...
class App extends Component {
  componentDidMount () {
    Qualtrics.initialize('BRAND ID', 'PROJECT ID', 'INTERCEPT ID', (initializationResult) => {
        if(initializationResult.passed) {
            ...
        }
    });
  }
}
...

function evaluateTargetingLogic(callback)

evaluates currently initialized intercept and calls callback

@parameters callback (function) - optional method called if defined

@return TargetingResult (object) - returned in callback, see TargetingResult for more info

Use case example - add a button so the user can click to evaluate targeting logic:

Qualtrics.evaluateTargetingLogic((targetingResult) => {
  if (targetingResult.passed) {
    ...
  }
});

function display()

displays creative in the view controller

@return Promise (object) - returns a Promise object that either resolves to true or false depending on display() succeeds or fails respectively

Use case example - display after evaluateTargetingLogic() passed:

Qualtrics.evaluateTargetingLogic((targetingResult) => {
  if (targetingResult.passed) {
    var displayed = await Qualtrics.display()
  }
});

function registerViewVisit(viewName)

record visits for a particular view name

@parameters viewName (string) - name of view to record

By keeping the intercept logic on the server rather than in the app, you can change when intercepts appear easily and without rebuilding and redistributing your app. You can use the registerViewVisit method to return data to the server about which how many total and unique views the user has seen. These statistics can be used to enable more complex logic around displaying surveys and other actions.

Qualtrics.registerViewVisit('VIEW NAME');

function resetTimer()

resets timer used for Time Spent In App logic

Qualtrics.resetTimer();

function resetViewCounter()

resets view count used for View Count logic

Qualtrics.resetViewCounter();

function setString(propertyKey, propertyString)

sets string value for specified key in properties

@parameters propertyKey (string) - string key for property propertyString (string) - string value associated with specified property key

By using the properties, you can push data back to the server, which can pass it on to your survey as embedded data. In the example below, the app will send the user's first name and age back to the server to be used as piped text in the survey. If the app requires the user to create an account, the user's first name should be readily available.

Qualtrics.setString('firstName', 'John');

function setNumber(propertyKey, propertyNumber)

sets double value for specified key in properties

@parameters propertyKey (string) - string key for property propertyString (number) - number value associated with specified property key

Qualtrics.setNumber('age', 42);

function setDateTime(propertyKey)

sets datetime stamp value for specified key in properties

@parameters propertyKey (string) - string key for property

Qualtrics.setDateTime('loginTimestamp');

function setLastDisplayTimeForIntercept()

sets the lastDisplayedTime for specified interceptId to now

@parameters interceptId (string) - The ID of the intercept for which the last display time is being set

Qualtrics.setLastDisplayTimeForIntercept('INTERCEPT ID');

function displayTarget()

displays evaluated TargetingResult in webview; this bypasses showing the Creative

Qualtrics.evaluateTargetingLogic((targetingResult) => {
  if (targetingResult.passed) {
    Qualtrics.displayTarget();
  }
});

class InitializationResult

@fields passed (boolean) - whether or not Qualtrics.initialize() succeeded message (string) - initialization message used to determine initialization status

class TargetingResult

@fields passed (boolean) - whether or not target evaluation succeeded surveyUrl (string) - link to the survey in creative where logic evaluation passed. url used to display survey in display() targetingResultStatus (string) - TargetingResultStatus error (string) - string

@functions recordClick() - records click to the server associated with intercept recordImpression() - records an impression to the server associated with intercept