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

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:

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

privateasync Task InitializeSwrveSDK()

{

// Configure here anything extra like in-app custom button listener,

// push notifications and push payload listener or dialog listeners.

SwrveConfig config=newSwrveConfig();

// To use the EU stack, include this in your config.

// config.SelectedStack = Swrve.Stack.EU;

// Configure here anything extra like in-app custom button listener,

// push notifications and push payload listener or dialog listeners.

await SwrveSDK.Instance.InitAsync(<app_id>,<api_key>,config);

}

protectedoverride async voidOnLaunched(LaunchActivatedEventArgse)

{

Frame rootFrame=Window.Current.Content asFrame;

if(rootFrame==null){

// Initialize the SDK when the app has been launched for the first time

await InitializeSwrveSDK();

}

}

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

1

2

3

4

5

6

7

8

9

10

11

protectedoverride async voidOnActivated(IActivatedEventArgs args)

{

base.OnActivated(args);

varrootFrame=Window.Current.Content asFrame;

if(rootFrame==null)

{

// Initialize the SDK when the app has been started from an activation

await InitializeSwrveSDK();

}

SwrveSDK.Instance.OnActivated(args);

}

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

1

2

3

4

5

6

7

privateasync voidOnSuspending(objectsender,SuspendingEventArgse)

{

vardeferral=e.SuspendingOperation.GetDeferral();

// Save application state and stop any background activity

await SwrveSDK.Instance.OnSuspendingAsync();

deferral.Complete();

}

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

1

2

3

4

privateasync voidOnResuming(objectsender,objecte)

{

await SwrveSDK.Instance.OnResumingAsync();

}

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.

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:

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:

Click the Live Services site link and register the app. Take note of the Application Secret.

Access your app in Swrve, and under the Setup menu, click Integration Settings.

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.

Associating Your Application With Windows Store

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

Open your project.

Right-click your project in the Solution Explorer.

Click Store – Associate App with the Store…

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.

1

SwrveSDK.Instance.Event("custom_event");

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

1

2

3

4

5

SwrveSDK.Instance.UserUpdate(newDictionary<string,string>{

{"premium","true"},

{"level","12"},

{"balance","999"}

});

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:

1

swrve.UserUpdate("last_purchase",DateTime.UtcNow);

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.

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.

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

1

2

SwrveIAPRewards rewards=newSwrveIAPRewards("Gold",1000);

SwrveSDK.Instance.IAP(10,"gold_pack_1",9.99,"USD",rewards);

Enabling IAP Receipt Validation

To enable validation of Windows Store IAP receipts in Swrve:

On the Setup menu, click Integration Settings.

Under IAP Validation, in the Windows Package Family Name section, enter the Package Family Name associated with your application in the Windows Store.

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.

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:

1

2

3

4

5

varresourceManager=SwrveSDK.Instance.ResourceManager;

// Then, wherever you need to use a resource, pull it from SwrveResourceManager.