Follow

Setting Up WNS with the ApmetrixWindows Runtime Component SDK

This document provides reference information for implementing WNS in your app/game for Windows 8.1 Desktop/Tablet (e.g. Surface tablet) or Windows Phone 8.1 device. It is recommended that you complete the SDK integration before implementing the topics in this article. 

Apmetrix's WNS implementation provides support for Toast Text notifications. At this time we do not support Live Tiles or Image Toasts

Table of Contents

  • Registering your App with the Windows App Store
  • Uploading your Credentials to the Apmetrix Platform
  • Setting up your App to receive Toast Notifications
    • Setting up Apmetrix Push Analytics

 

Registering your App with the Windows App Store

In order to be able to receive Push Notifications, you will need to set up your application in the Windows Store.

Register your app with the Dashboard

To register:

  • Go to the Windows Store apps page of the Windows Dev Center and sign in with your Microsoft account.
  • Once you have signed in, click the Dashboard link.
  • On the Dashboard, select Submit an app.

sub_app.png

  • On the Submit an app page, select App name.

app_name.png

  • Provide a unique name for your app. Enter the name and click the Reserve name button. If the name is available, it is reserved for your app. Once you have successfully reserved a name for your app, the other details become available to modify should you choose to do so at this time.

 

Obtain the credentials for your app

When you reserved a name for your app, the Windows Store created your associated credentials. It also assigned associated identity values—name and publisher— that must be present in your app's manifest file (package.appxmanifest). If you have already uploaded your app to the Windows Store, these values will have automatically been added to your manifest. If you have not uploaded your app, you will need to add the identity values to your manifest manually.

  • Select the Services link.

services.png

  • Then under the Microsoft Azure Mobile Services you will want to click on the Live Services Site as shown in the screen shot below

mobile_services.PNG

  • This will then open up a window with your App's Identifying keys. The ones in the picture below are grayed out for security purposes. Keep this window open as you will need to copy data from here into the Apmetrix Platform. You will need the Package SID and the Client Secret

secrets.PNG

Uploading your Credentials to the Apmetrix Platform

 

Now log into the Apmetrix Dashboard (https://www.apmetrix.com/login/) and click on your profile pic then go to
Administration->Accounts then click on your Application. Switch to the Task tab and add the
Push Notifications Task.

In the settings Tab give the task a Name and then in the MS WNS SID Field add your Package ID & in the MS WNS Client Secret add your Client Secret. Click ok and now you have given Apmetrix the tools to send your App Toasts. Next we will discuss how to setup your App to receive these messages.

 

Setting up your App to receive Toast Notifications

Now you can automatically associate your project with the application in the Windows Store by right clicking on the project and selecting Store->Associate App with the Store, as shown in the picture below. This will popup a series of boxes and ask you to select the app that is on the Windows Store Dashboard that you created above. If you are setting up Toasts for a Windows Phone 8.1 App please read this link as it explains how to link your Phone App with a Store App. Associating your Windows Phone App with a Store App

assocStore.png

After associating your app with the store you should see a Package.StoreAssociation.xml in your App's folders via the Solution Explorer. Next you will want to open up your app's Package.appxmanifest file. You will want to go to the Application Tab and in the Notifications area set Toast Capable: to Yes as shown in the picture below.

ToastCap_Yes.PNG

Once that is set go ahead and click on the Declarations Tab. 

appDecla.png

Here we will declare the background task. This background task is used to update the App's Push Channel to ensure Toasts can reach the device. 

bgTaskDec.PNG

In the Available Declarations select Background Tasks and then click on Add.

addedBGTask.PNG

Fill it in as shown in the picture above save the file. Make sure to add the WNS Permission on the init sdk call. Otherwise the SDK will not initialize the WNS System.

WinJS:

var ApmetrixPush = Apmetrix.use_Push();

Apmetrix.init(123456, '1.0', '123456789QWERRTTY', ApmetrixPush);

C#:

await Apmetrix.init(123456, "1.0", "123456789QWERRTTY", Apmetrix.Use_Push());

C++:

Apmetrix::init(123456, L"1.0", L"123456789QWERRTTY", Apmetrix::Use_Push());

 

Setting up Apmetrix Push Analytics

Next we will setup each the app to take advantage of the Apmetrix Push Analytics. We will be adding code to handle Resuming, Launching and Suspending events. Since the Apmetrix sdk is exposed in a static interface we can get away with calling init & end sessions in the App file. It is recommended you take a look at the Windows App Lifecycle Article as it contains important lifecycle information.

WinJS:

The changes will occur in the default.js file

Inside the main function denoted with (function () { "use strict"; you will want to declare three appListeners if you do not already have them

app.addEventListener("activated", activatedHandler, false);
app.addEventListener("checkpoint", checkpointHandler, false);
Windows.UI.WebUI.WebUIApplication.addEventListener("resuming", resumingHandler, false);

Then outside of the main JS function you will need to declare the Resuming and Checkpoint handlers

The Resuming Handler is called when the app comes into the foreground and you will want to ensure the Apmetrix SDK is active. The Checkpoint Handler is called when the app is terminated or is sent to the background. You will want to ensure you have shutdown the Apmetrix SDK session

function resumingHandler()
{
     init(123456, '1.0', '123456789QWERRTTY', ApmetrixPush);
}

function checkpointHandler(eventArgs) {
    var stateObject = new Object();

    eventArgs.setPromise(endSession());
}

 Finally in the activatedHandler(eventArgs) you will want to call two functions. As an example here is our handler. You will want to add Apmetrix.setLaunched() in the  activatedHandler(eventArgs). The Apmetrix function returns back clean args or an empty string if no other Args exist. It is also recommended you call the Apmetrix sdk init to make sure a session is active from the get go.

function activatedHandler(eventArgs) {
     if (eventArgs.detail.kind == Windows.ApplicationModel.Activation.ActivationKind.launch) {
       //// Check whether my session state variables are valid.
       //// If so, retrieve the application data saved in the checkpoint handler
       launchArgs = Apmetrix.setLaunched(eventArgs.detail['arguments']);
       Apmetrix.init(123456, '1.0', '123456789QWERRTTY', ApmetrixPush);

       eventArgs.setPromise(WinJS.UI.processAll());
     }
}

 

C#:

The changes will occur in the App.xaml.cs file

You will want your public App() function to include the following

this.InitializeComponent();
this.Suspending += this.OnSuspending;
this.Resuming += this.App_Resuming;

You will need to declare the App_Resuming() if you dont have a resuming function already. The Resuming function will call the Apmetix Init() with credetials. This is done to ensure the SDK is active.

private void App_Resuming(Object sender, Object e)
{
     Apmetrix.init(123456, "1.0", "123456789QWERRTTY", Apmetrix.Use_Push());
}

 

We will now add a call in the OnSuspending() to end the Apmetrix Session when the app is closed or sent to the background

private void OnSuspending(object sender, SuspendingEventArgs e)
{
     var deferral = e.SuspendingOperation.GetDeferral();

     // TODO: Save application state and stop any background activity
     ApmetrixWind_RTC.Apmetrix.endSession();
     deferral.Complete();

 

Finally  you will want to add Apmetrix.setLaunched(e.Arguments) in the first line of OnLaunched(). The Apmetrix function returns back clean args or an empty string if no other Args exist.

protected override void OnLaunched(LaunchActivatedEventArgs e)
{

string args = Apmetrix.setLaunched(e.Arguments);

Apmetrix.init(123456, "1.0", "123456789QWERRTTY", Apmetrix.Use_Push());

.....

}

You have now setup your app to use the Apmetrix Push Analytics.

 

C++:

The changes will occur in the App.xaml.cpp & App.xaml.h files

In your App.xaml.h in the private add

void OnResuming(Object^ sender, Object^ e);

Then in the App.xaml.cs you will want to set your App constructor to include

App::App()
{
     InitializeComponent();
     Suspending += ref new SuspendingEventHandler(this, &App::OnSuspending);
     Resuming += ref new EventHandler<Platform::Object^>(this, &App::OnResuming);
}

Then you will want to setup your OnResuming() to look like. This is called when your app comes back to the Foreground from the Background

void App::OnResuming(Object^ sender, SuspendingEventArgs^ e)
{
    (void)sender; // Unused parameter
    (void)e; // Unused parameter

    Apmetrix::init(123456, L"1.0", L"123456789QWERRTTY", Apmetrix::Use_Push());

}

Then you will want to setup your OnSuspending() to look like. This is called when your app is terminated or is about to be sent to the background

void App::OnSuspending(Object^ sender, SuspendingEventArgs^ e)
{
     (void) sender; // Unused parameter

     (void) e; // Unused parameter
     SuspendingDeferral^ deferral = e->SuspendingOperation->GetDeferral();

     // TODO: Save application state and stop any background activity
     ApmetrixWind_RTC::Apmetrix::endSession();
     deferral->Complete();
}

Finally you will want to setup your OnLaunched() to include the Apmetrix setLaunched(e->Arguments).  The Apmetrix function returns back clean args or an empty string if no other Args exist. You will also want to call the Apmetrix init() to make sure the SDK session is Active on Launch

void App::OnLaunched(LaunchActivatedEventArgs^ e)
{
     //Grabs the Launch Args. Requried when using Apmetrix Push
     Platform::String^ args = ApmetrixWind_RTC::Apmetrix::setLaunched(e->Arguments);

     Apmetrix::init(123456, L"1.0", L"123456789QWERRTTY", Apmetrix::Use_Push());

....

}

  

Your app is now ready to take full advantage of the Apmetrix WNS Toast System. To send a Toast go to the Apmetrix Platform, click on your profile pic and go to Messages->Send Message. Select Microsoft and fill in the parameters and click Send. If everything was setup correctly you will see a Toast Message.

Have more questions? Submit a request