Last modified September 19, 2019 by Shelly Wolfe

Cordova (PhoneGap)

Swrve is a single integrated platform that delivers everything you need to drive mobile engagement and create valuable customer relationships on mobile.

The Swrve Cordova SDK plugin enables your app to use all of the features available. This guide contains all the information you need to integrate the SDK plugin into your app.


Requirements

  • The App ID and API Key for your app. This information is available in Swrve on the Integration Settings screen (on the Settings menu, select Integration settings).
  • Note: The Cordova plugin uses the native SDKs for iOS and Android. You can find more information about the native SDKs in the platform-specific documentation.
  • NPM version 6.7.0 or above
  • The Cordova command-line interface (CLI) version 9.0.0 or above
  • cordova-ios 5.0.0 or above
  • cordova-android 8.0.0 or above
  • cordova-node-xcode 2.0.0 or above

Installing the SDK

Swrve has an open source SDK repository. There are two options for downloading the latest public Cordova SDK plugin:

  • Install the plugin from NPM using the following command:
    cordova plugin add cordova-plugin-swrve
  • Download the plugin from the GitHub public repository or clone the repository.

Initializing the SDK Plugin from a template

To help you quickly get started with an empty project that already includes the Swrve config, we’ve provided a template using the Cordova App Templates pattern. Use the Cordova CLI to check out this repository and build it as a project. For example:

Change hello, com.example.hello, and HelloWorld to fit the application directory name, bundle identifier, and name you need.

Once the template is created, edit the properties of config.xml as needed The following section describes how to modify your config.xml.


Adding the SDK Plugin to your Project

To simplify project initialization, the Swrve Cordova SDK plugin uses Hooks to generate the majority of the settings and code in the final project. This also makes it easier to upgrade to future versions of iOS and Android Cordova.The plugin includes two scripts and boilerplate code that are used during the after_plugin_install and after_prepare lifecycle states of a Cordova build. To activate them and add your own settings, you must perform the following steps:

Step 1: Add the Swrve Cordova SDK plugin to your project:

Step 2: Modify the config.xml at the root of your Cordova/PhoneGap project as shown in the platform-specific examples below. Replace <swrve_app_id> and <swrve_api_key>  with your own app ID and API key.

Depending on your data requirements, Swrve stores all customer data and content in either our US or EU data centers. If your app uses EU data storage and URL endpoints (that is, you log into the Swrve dashboard at https://eu-dashboard.swrve.com), include the EU stack information in the example below. If you have any questions or need assistance configuring the SDK for EU data storage, please contact support@swrve.com.

iOS

Note: We do not manage application signing or entitlements on the main app. You need to add your own config.xml changes to handle things like remote notifications. (See Push Notifications for more information.)

Android

Step 3: Add both platforms via Cordova CLI. If you plan on using push notifications, leave this step until you have completed the Push Notifications section of this guide. Otherwise, use the following commands to generate your project.


User identity

Swrve supports an Identify API to find preexisting user identities that an app has logged either on a single device or multiple devices. You can now identify users and then track and target them safely across multiple devices, platforms, and channels. For more information, see Tracking your users with Swrve User Identity.

The external ID is a non-discoverable key that identifies your user across multiple channels and platforms. Emails or other personally identifiable information (PIIs) are not accepted as external user IDs, they will be rejected on the server side. Before you implement the Identity service, please consult with your Customer Success Manager at support@swrve.com for some guidance on best practices to follow in your integration.

Identify

When you are ready, call the Identity API with your external user ID:

If the call fails, then the user will not be correctly linked on the Swrve backend system, which may affect reporting and audiences where the user is logging in on multiple devices. We recommend not queuing or sending events until the identify call completes successfully.


Push notifications

Use Swrve’s push notification campaigns to send personalized messages to your app users while they’re outside of your app or send silent background app updates. For more information, see Intro to push notifications.

Push notifications are disabled by default. To enable them using our hook system, complete the following steps:

Step 1: Modify the config.xml at the root of your Cordova/PhoneGap project.

iOS

  • Ensure the swrve.pushEnabled preference is present and set to true. This uses a hook system to generate a Service Extension for rich media push capabilities.
  • To track users who are influenced by a push notification, the swrve.appGroupIdentifier preference is required. For more information on how we track influenced users, see the iOS Integration Guide. You must complete the additional required steps in the Apple Developer portal.
  • We do not handle signing and capabilities for the main target, so you need to open the generated Xcode project and enable the Push Notification Capability. If you also decide to use App Groups, you need to enable that capability as well. Finally, ensure that your team and app provisioning is set for both the service extension and main target. For more information on Capabilities please refer to Step 4 of Rich Media Push Notifications in our iOS Integration Guide.

Android

  • Ensure the swrve.pushEnabled preference is present and set to true. This uses a hook system to add all changes to the Manifest.xml file and add the appropriate boilerplate code.
  • Android push notifications require you to specify the images that appear in the status bar on receiving a notification. We require two images with specific names. material_icon.png is the icon that appears in the status bar for devices running Android api levels greater than 20 and icon.png  is for Android devices below api level 21. Put both of these into a drawable folder somewhere at the root of your project and include the path to the directory under the preference swrve.drawablePath
  • The SwrveSDK uses Firebase Cloud Messaging for push notifications. To work correctly, it requires a google-services.json file located at the root of the module. The SwrvePlugin will do this via hook for you, but you need to provide a path for swrve.googleServicesPath to your own google-services.json.

Step 2: If you want to perform custom processing of the push notification engagement payload, you can add a listener on the JavaScript layer that will return the payload of a notification when it is engaged with:

Step 3: If you have already generated a platform, use remove and add commands to regenerate your platforms and add the changes included in the push notification hooks.

iOS provisional authorization for push

In iOS 12, Apple added a feature for provisional authorization of push notifications. This feature enables you to send push notifications as soon as a user opens your app for the first time, without requiring the user to opt-in. The notification is delivered directly to the device’s Notification Center and when the user views the notification, the message automatically includes a built-in prompt asking if they want to continue to receive notifications.

By default, the Swrve SDK requests full push permission the first time the user launches your app. To implement provisional authorization for iOS, set different events for both the provisional and full authorization in the iOS platform of your config.xml.

Configuring iOS silent notifications

The purpose of a silent notification is to refresh your app’s data when it is running in background, for example, a content update. You should never call the SDK from a silent notification. Note, iOS does not permit silent notifications to wake up the app if it is completely closed (that is, a user has double-clicked the home button and swiped up to close the app). If the app is closed, you can only update the badge number.

To enable silent push notifications in your app, complete the following:

Step 1: Early in your application config, include a listener for silent notifications.

Step 2: Modify the Info.plist of the Xcode project that is generated in platforms. You can do this by adding the following addition to the iOS platform in your config.xml file.


In-app messages and Conversations

Swrve’s in-app messages and Conversations campaigns are available as soon as you complete the basic integration described above. These features enable you to send personalized messages to your app users while they’re using your app. For more information, see Intro to in-app messages and Intro to Conversations.

To test in-app messages or Conversations in your app, you need to first create the campaign in Swrve. For more information, see Creating in-app messages and Creating Conversations.

In-app message and Conversation deeplinks

When creating in-app messages and Conversations in Swrve, you can configure message buttons to direct users to perform a custom action when clicked. For example, you might configure a button to direct the app user straight to the app store to provide a rating.

Swrve’s default deeplink behavior is to treat custom actions as URLs, therefore use your existing custom URL scheme. Custom URL schemes need to be configured on a per-platform basis.

Once the custom URL scheme is set, your app can receive and direct users from outside of the app.

If you would like to process the custom action completely on your own, you must add a custom listener to the Swrve SDK before its initialization.

In-app message custom actions

For in-app messages, it is also possible to override this behavior of treating custom actions as URL deeplinks and integrate custom actions to direct users to a sale, website, or other target when they click an in-app message. Use the following callback:


Sending events

The Swrve SDK automatically sends certain events and also enables you to track user behavior by sending custom events. In turn, you can use app-generated events to trigger in-app messages, while both app- and server-generated events help you define segments and perform in-depth analytics.

Custom events

To send a custom event, include the below example in a method where you want to send an event to Swrve.

Requirements for sending custom events:

  • Do not send the same named event with different case. For example, if you send tutorial.start, then ensure you never send Tutorial.Start.
  • Use a period (.) in your event names to organize their layout in the Swrve dashboard. Each ‘.’ creates a new branch in the Event name column of the Events report, and groups your events so they are easy to locate.
  • Do not send more than 1000 unique named events.
    • Do not add unique identifiers to event names. For example, Tutorial.Start.ServerID-ABDCEFG
    • Do not add timestamps to event names. For example, Tutorial.Start.1454458885
  • Do not use the swrve.* or Swrve.* namespace for your own events. This is reserved for Swrve use only. Custom event names beginning with Swrve. are restricted and cannot be sent.

Event payloads

You can add and send an event payload with every event. This allows for more detailed reporting around events and funnels.

Notes on associated payloads:

  • The associated payload should be a dictionary of key/value pairs; it is restricted to string and integer keys and values.
  • There is a maximum cardinality of 500 key-value pairs for this payload per event. This parameter is optional, but only the first 500 payloads are displayed in the dashboard. The data is still available in raw event logs and for audience filtering.
  • It is not currently possible to use payloads as triggers for push notifications. Use events for these purposes.
  • If you want to use event payloads to target your campaign audiences, you can configure up to 10 custom events with a maximum of 20 payloads per event for audience filtering purposes. For more information, see Targeting your audience by event payloads.

For example, if you want to track when a user starts the tutorial experience, it might make sense to send an event named tutorial.start and add a payload time that captures how much time it took the user to complete the tutorial.

Custom user properties

The Swrve SDK sends certain user properties by default and also enables you to assign custom properties to update the user’s status. (For a full list of the default user properties, see Assigning user properties.)

For example, you could create a custom user property called premium, and then target non-premium users and premium users in your campaigns.

Virtual economy events

To ensure virtual currency events are not ignored by the server, make sure the currency name configured in your app matches exactly the Currency Name you enter in the App Currencies section on the App Settings screen (including case-sensitive). If there is any difference, or if you haven’t added the currency in Swrve, the server will ignore the event and return an error event called Swrve.error.invalid_currency. Additionally, the ignored events are not included in your KPI reports. For more information, see Add your app.

If your app has a virtual economy, send the purchase event when users purchase in-app items with virtual currency.

Send the currency given event when you give users virtual currency. Examples include initial currency balances, retention bonuses and level-complete rewards.

In-app purchase events and validation

If your app has in-app purchases (IAPs), send the IAP event when a user purchases something with real money.

Unvalidated IAP

Due to the nature in which Cordova uses a shared JavaScript, we cannot provide an SKReceipt or Google Play response in a JavaScript way. It is available natively, which is covered in the iOS and Android integration guides. However, if you want to simply build revenue reports for your app but do not have or want the receipt to be validated by our servers, use the following unvalidatedIap function:

With your IAPs, you can also track rewards provided for the IAP. This could be something like in-game currency or access to a premium service. These are provided as an optional JSON object that is made up of two JSON lists. One is for items received and the other is related to a virtual currency that you have registered in your Swrve dashboard. The below example includes one of each:


Resource A/B testing

Integrating Swrve’s resource A/B testing functionality enables you to use Swrve to test how users respond to changes to the native app content. For more information about resource A/B testing, see Intro to resource A/B testing.

To get the latest version of a resource from Swrve, use the following:

If you want to be notified whenever resources change, you can add a callback function as follows:


Troubleshooting

Since this SDK is build primarily for the Cordova CLI, we run the majority of our tests against that tool. Ionic and PhoneGap are still tested internally to help increase overall compatibility. This section provides workarounds for known issues with those platforms.

PhoneGap

When adding the android platform to your PhoneGap project, the PhoneGap CLI selects android-cordova 7.1.1 that targets Android 27. Our Plugin uses an Android SDK that targets 28 and therefore may cause Gradle build issues. To ensure this doesn’t happen, please use the following steps:

Step 1: Once the Android platform is generated, open the project.properties file inside: platform/android/project.properties.

Step 2: Replace the target value from android-27 to android-28 and re-sync your Gradle build. It should build now.


Testing your integration

After you’ve completed the above, the next step is to test the integration. For more information, see Testing your integration.


Upgrade instructions

If you’re moving from an earlier version of the Cordova SDK to the current version, see the Cordova SDK upgrade guide for upgrade instructions.