Last modified April 15, 2016 by Shelly Wolfe

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 PhoneGap 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 Setup menu, click Integration Settings).
  • Note: The PhoneGap plugin uses the native SDKs for iOS and Android. You can find more information about the native SDKs in the platform-specific documentation.

Installing the SDK

Swrve has an open source SDK repository:

  • Download the SDK plugin from the Github releases page.
  • Download the SDK plugin from the Github public repository or clone the repository. Note that it contains a submodule that will not be present in the zip version and you’ll have to sync it if cloning the repository.

Basic Integration

Complete the following steps for a basic integration.

Step 1: Install the following plugin in your project:

Step 2: Initialize the Swrve SDK with optional support for Push Notifications:

Depending on your data requirements, Swrve stores all customer data and content in either our US or EU data centers. If you require EU data storage, include the EU stack information in the examples below to configure the SDK to point to Swrve’s EU-based URL endpoints. If you have any questions or need assistance configuring the SDK for EU data storage, please contact support@swrve.com.

iOS

Initialize the Swrve SDK in your AppDelegate.m using your Swrve App ID and Swrve API Key in  <app_id> and <api_key> respectively. Then add support for remote notifications:

Android

Add a custom Application class to platforms/android/src/your/package/Application.java and define it in your platforms/android/AndroidManifest.xml.

AndroidManifest.xml changes

Sample Application.java

Set the <app_id> and <api_key> fields of the component to your Swrve App ID and Swrve API Key.

(Optional for GCM push): Make the same AndroidManifest.xml modifications as the native SDK to your PhoneGap app as described in the Android Integration Guide, under Push Notifications. If you don’t want to use Google GCM pushes, you can compile against our standard SDK by changing the plugin’s dependency to compile com.swrve.sdk.android:swrve:X.X.X (where X.X.X is the version of the SDK; for example, 4.4.0) and modifying the plugin calls.

Step 3: Use the window.plugins.swrve plugin.


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 on an in-app message. Use the following callback:


Push Notifications

Swrve’s push notification campaigns enable you to send personalized messages to your app users while they’re outside of your app. Swrve Push Notifications are available for iOS and Android. For more information, see Intro to Push Notifications.

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

Step 1: Enable push notifications when initializing the Swrve SDK. For Android Push Notifications, you must provide the project number obtained from the Google Developer Console to the SDK on initialization:

iOS

Android

Step 2: Time the push permission request.

Follow the steps in the iOS and Android platform-specific guides to time the push permission.

Step 3: If you want to perform custom processing of the push notification payload, create the following class and add this code:


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 10 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 step 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.

iOS – Enabling IAP Receipt Validation

To enable IAP receipt validation, please review the native SDK information in the iOS Integration Guide.

You need to use the native code to respond to verifiable IAP purchases.

iOS – Unvalidated IAP

If you want to build revenue reports for your app but do not have or want the receipt being validated by our servers, use the following function:

Android – IAP

The functions provided by the PhoneGap wrapper on the Android platform are exactly the same as the ones provided in the native Android SDK. Please review the Android Integration Guide for more information:


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:


Testing Your Integration

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


Plugin Demo

For a general demo of the Swrve PhoneGap Plugin, see the Swrve PhoneGap demo on Github.