Last modified April 13, 2016 by Shelly Wolfe

Windows

Swrve is a single integrated platform that delivers everything you need to drive mobile engagement and create valuable customer relationships on mobile.The Swrve Windows SDK enables your app to use all of the features available. This guide contains all the information you need to integrate the SDK into your app.


Requirements

  • The Swrve Windows SDK supports Windows 10 only.
  • 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).
  • To have your Swrve dashboard enabled for Windows 10, contact your Customer Success Manager at support@swrve.com.

Installing the SDK

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


Basic Integration

After you have installed the SDK, complete the following steps for a basic integration. Replace <app_id> and <api_key> with your app ID and API key.

Initialize the SDK in Your Application

You must initialize the SDK when your application is launched or activated. You also have to notify the SDK that your application is being suspended or resumed.

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 example 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.

Step 1: Add the following code snippet to the OnLaunched method of your application:

Step 2: Add the following to your application’s OnActivated method:

Step 3: Add the following to your application’s OnSuspending method:

Step 4: Add the following to your application’s OnResuming method:

The project is now ready to compile and run in the Windows 10 simulator.

Basic integration of the Swrve SDK enables you to track important metrics and run in-app messages and Conversations campaigns. To make use of additional Swrve features, complete the following sections as required.

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.

Reacting to In-App Message Deeplinks

By default the Swrve SDK launches your deeplinks when the user clicks the button. If you want to process the action set in a custom button yourself, add a handler to the following event before the SDK is initialized:

Listening for In-App Message or Conversation Dialogs

The SDK offers the following events that you can listen to if you want to determine if a dialog is being shown by the Swrve SDK:


Push Notifications

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

Push notifications are disabled by default. To enable them, specify that you require push notifications in the SwrveConfig object used for initialization and attach a push notification handler:

When a user engages with a push notification, the PushNotificationEngaged event is invoked. To react to custom payloads, use code similar to the following snippet:

The remainder of the initialization process depends on how you want to request permission from the user to accept push notifications.

Timing the Device Token (Push Permission) Request

When a user first installs a push-enabled app, the app requests the latest device token for push notifications. This triggers a permission request to the user to accept push notifications from the app. Swrve has built-in functionality to manage the timing of this request. There are two options:

  • Start of the first session (default configuration) – This is the simplest option and requires no additional code changes.
  • When one of a list of events is triggered – To request permission when certain events are triggered, add the event names to SwrveConfig.PushNotificationEvents when you initialize the SDK. For example:

    If a user never triggers these events, they will never be available for push notifications, so select events that are most likely to be triggered by all but the most transient of users.

Creating and Uploading Your Windows SID and Secret Key

To enable your app to send push notifications to Windows devices, you need to register the app in the Windows Dev Center and the Live Services site.

  1. Go to your app’s Services – Push Notifications section in the Windows Dev Center.
  2. Click the Live Services site link and register the app. Take note of the Application Secret.
    ms_app_reg
  3. Access your app in Swrve, and under the Setup menu, click Integration Settings.
  4. Under the Windows Push Notification Service section, enter the Package SID (must start with ms-app://) and the Application Secret key that you got from Live Services.
    windows_pfn

Associating Your Application With Windows Store

To be able to receive push notifications, your app needs to be associated with a Windows Store app:

  1. Open your project.
  2. Right-click your project in the Solution Explorer.
  3. Click Store – Associate App with the Store…
  4. Follow the instructions to associate your app with the desired store.

This process should create a Package.StoreAssociation.xml file and enable you to start receiving push notifications.


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 tree 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.
  • It is not currently possible to use payloads as triggers or for filters in the dashboard. Use events for these purposes.

For example, if you want to track when a user starts the tutorial experience, it might make sense to send an event tutorial.start and add a payload time that captures how long the user spent starting 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 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.

Example of group of user properties

Example of a single date-typed user property

Use the DateTime object to send a DateTime user property; for example, the current date at the time of a user purchase:

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 event will be ignored and return an error event called Swrve.error.invalid_currency. Additionally, the ignored events will not be 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

If your app has in-app purchases (IAPs), send the IAP event when a user purchases something with real money. The IAP event enables Swrve to build revenue reports for your app and to track the spending habits of your users. Note that IAP validation will be available soon and you will need to update the SDK at that time.

Notify Swrve when an in-app purchase occurs as follows:

You can also send revenue events without a receipt using the following method:

Enabling IAP Receipt Validation

To enable validation of Windows Store IAP receipts in Swrve:

  1. On the Setup menu, click Integration Settings.
  2. Under IAP Validation, in the Windows Package Family Name section, enter the Package Family Name associated with your application in the Windows Store.
  3. Click Save.

The Windows Package Family Name is used when verifying digital signatures of your purchase receipts. This ensures that your revenue figures are as accurate as possible (ignoring pirates and cheaters).

Generally, you enter the Package Family Name when configuring the Integration Settings screen as part of the Swrve onboarding process. You can edit the settings on this screen at any time.

To view your Package Family Name, access the Microsoft Windows Dev Center page for your application and navigate to App management > App identity. The Package Family Name is displayed as illustrated below.

WindowsPFN

Verifying IAP Receipt Validation

Use the following events to monitor the success of IAP receipt validation:

  • swrve.valid_iap – fired if receipt verification is successful and the receipt is valid.
  • swrve.invalid_iap – fired if receipt verification is successful and the receipt is invalid.

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 using the Resource Manager, use the following:

If you want to be notified whenever resources change, then add an event handler 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.


Upgrade Instructions

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


SDK Demo

For a general demo of the Swrve Windows SDK, see the Swrve Windows SDK demo on Github.