Callstats.io Integration

Callstats offers collection and in-depth analysis of your WebRTC connection statistics, and from IceLink 3.2.5 onwards Callstats integration is a snap! For more information on Callstats.io, what it does, how it can benefit your app, and how to set up an account, check it out here. To integrate your IceLink application with your Callstats.io account follow these simple instructions.

Callstats for Native Platforms

Creating a Callstats Account and App

The first step is to create your Callstats.io account. Callstats walks you through the process when you sign up. They also have lots of great documentation to help you get started. Once you have done that you will have configured a Callstats App and this is what you will integrate with your IceLink application using the Callstats AppId. Instructions for setting up integration credentials are available in the Callstats documentation here. Once you have the Callstats AppId you simply create an IceLink Callstats Client and use your AppId to configure this Client:

private FM.IceLink.CallStats.Client _CallstatsClient = null;
private string _CallstatsApplicationId = "012345678";

private fm.icelink.callstats.Client callstatsClient = null;
private String callstatsApplicationId = "012345678";
FMIceLinkCallStatsClient* _callstatsClient = NULL;
NSString* _callstatsApplicationId = @"012345678";

Callstats Client Authentication

In addition to configuring your Callstats AppId you will need to authenticate your Callstats Client. The recommended way to do this is using an ECDSA keypair. To authenticate, your client will use the private key against the public key you will configure in your Callstats App. IceLink provides a simple way to generate this keypair using the FM.IceLink.EcdsaCrypto utility class. You can generate the keypair using any other valid method if you wish. Here is C# code showing how to generate your keys using the IceLink utility method and then write the keys out to file:

Generating ECDSA Keys
EcdsaKey privateKey = EcdsaCrypto.CreateKey();
var privateKeyString = privateKey.GetString();
var publicKeyString = privateKey.ToPublic().GetString();
File.WriteAllText("private.pem", privateKeyString);
File.WriteAllText("public.pem", publicKeyString);

Once you have your public key you have to add it to your Callstats App's Security configuration. Callstats offers documentation on how to achieve this here. Once you have successfully created your public key in Callstats click "View" to see the configured key and get its Key Id. You will need this Key Id to create your client. It tells Callstats which key you are authenticating against.

Note that you need only generate your keys once. The public key is then added to your Callstats App's Security config, and your private key can be used from any application that has access to it. It is up to you to limit access to your private key.

At this point you have configured your Callstats App with your public ECDSA key and you have the corresponding Key Id, you have your private ECDSA key, and you are ready to use the private key with your IceLink Callstats Client. Here is an example of reading the private key from the PEM file you generated above and creating your Callstats Client:

// Read the private key in from file.
EcdsaKey callstatsPrivateKey = EcdsaKey.ParseString(System.IO.File.ReadAllText("path\to\my\private.pem"));


// The public Key Id created when you configured your public key in Callstats.
string callstatsEcdsaPublickeyId = "my-ecdsa-public-key-id";


_CallstatsClient = new Client(callstatsPrivateKey, _CallstatsApplicationId, callstatsEcdsaPublickeyId);

// Read the private key in from file.
byte[] encoded = Files.readAllBytes("path/to/my/private.pem");
fm.icelink.EcdsaKey privateKey = EcdsaKey.parseString(new String(encoded, Charset.defaultCharset()));


// The public Key Id created when you configured your public key in Callstats.
String callstatsEcdsaPublickeyId = "my-ecdsa-public-key-id";

callstatsClient = new Client(privateKey, callstatsApplicationId, callstatsEcdsaPublickeyId);
// Read the private key in from file.
NSString* keyPath = [[NSBundle mainBundle] pathForResource:@"private" ofType:@"pem"];
NSString* content = [NSString stringWithContentsOfFile:keyPath encoding:NSUTF8StringEncoding error:nil];
FMIceLinkEcdsaKey* privateKey = [FMIceLinkEcdsaKey parseStringWithStr:(NSString*) content];


// The public Key Id created when you configured your public key in Callstats.
NSString* callstatsEcdsaPublickeyId = @"my-ecdsa-public-key-id";


_callstatsClient = [[FMIceLinkCallStatsClient alloc] initWithPrivateKey:privateKey applicationId:_callstatsApplicationId ecdsaPublicKeyId:callstatsEcdsaPublickeyId];

Optional Client Configuration

Optionally you can add some additional info to your Callstats Client. These properties are useful when you are looking at results in your Callstats dashboard (or other views on your connection statistics) as they help identify the client that collected the stats. They are basically a tagging mechanism allowing you to know where the stats data originated. You can also optionally include information on the version of your app, and the OS and OS version the app was running on when the stats were collected.

_CallstatsClient.EndPointClientName = "NET";
_CallstatsClient.EndPointClientVersion = "1.0";
_CallstatsClient.EndPointAppVersion = "1.0.0";
_CallstatsClient.EndPointOS = ...
_CallstatsClient.EndPointOSVersion = ...

callstatsClient.setEndPointClientName("Android");
callstatsClient.setEndPointClientVersion("1.0");
callstatsClient.setEndPointAppVersion("1.0.0");
callstatsClient.setEndPointOS(...);
callstatsClient.setEndPointOSVersion(...);
_callstatsClient.endPointClientName = @"iOS";
_callstatsClient.endPointClientVersion = @"1.0";
_callstatsClient.endPointAppVersion = @"1.0.0";
_callstatsClient.endPointOS = ...;
_callstatsClient.endPointOSVersion = ...;

Collecting Connection Stats

Almost done. The last step is to add connections to your Callstats client. You already have plenty of experience creating IceLink connections. Integrating these with Callstats is as simple as adding the connection to the Callstats client. The parameters for adding the call are:

  • connection: Your IceLink connection object.
  • localUserId: A unique identifier for your user (supplied by your application).
  • sessionId: Your IceLink session Id.
  • remoteUserId: A unique identifier for the remote user (supplied by your application).
  • deviceId: A unique identifier for the device your application is running on (supplied by your application).
// Create your connections normally and then add connections to the Callstats Client.
_CallstatsClient.AddConnection(connection, localUserId, sessionId, remoteUserId, deviceId);

// Create your connections normally and then add connections to the Callstats Client.
callstatsClient.addConnection(connection, localUserId, sessionId, remoteUserId, deviceId);
// Create your connections normally and then add connections to the Callstats Client.
[_callstatsClient addConnection:connection userId:_username deviceId:deviceId confId:_sessionId remoteId:clientId];

Callstats for Web

Creating a Callstats Account and App

Those amongst you looking for Callstats integration for your Web apps will have noticed the lack of JavaScript examples in the above discussion. Never fear, IceLink supports Callstats integration for Web! We have simply broken out the JavaScript discussion because the API differs slightly from native platforms. As discussed for the native Callstats integration, the first step is to create your Callstats.io account, create a Callstats App, and get your AppId.

Adding the Callstats JavaScript Library Dependency

Callstats already provides a JavaScript library and documentation for integrating your Web app using it. Rather then reinvent the wheel, our JavaScript API simply wraps Callstats' library. In addition to including a reference to the IceLink JavaScript API for Callstats, this means you will have to include the Callstats library in your Web app like this:

Include the Callstats Library Dependency
<script src="https://api.callstats.io/static/callstats.min.js"></script>
<script type="text/javascript" src="lib/fm.icelink.callstats.js"></script>

Creating your Callstats Client

Creating the Callstats Client in JavaScript is even simpler than it is in the native API because JavaScript uses a different authentication method. The reason for this is due to Callstats' own best practices for authentication. Callstats recommends using ECDSA keys for authenticating when using their REST API, which is what we use in the native IceLink API. In their JavaScript library Callstats uses App Id and App Shared Secret for authentication, and we have based our JavaScript API off of Callstats' JavaScript library and followed their lead. So, for JavaScript, you simply get your App Id and configure an App Shared Secret credential for your App (instead of an ECDSA Public Key). When you create the App Shared Secret credential for your Callstats App the actual value of the shared secret is created for you by Callstats. This is different than creating an ECDSA credential (which requires you to generate your own keys). You then use your App Id and your App Shared Secret to construct your client:

this.callstatsApplicationId = '012345678';
this.callstatsApplicationSecret = 'my-callstats-application-shared-secret';


...

var client = new fm.icelink.callstats.Client(this.callstatsApplicationId, this.callstatsApplicationSecret)

That's it! You have created a client and it will authenticate using your configured App Shared Secret. You can now start collecting Connection statistics.

Protect Your Shared Secret

It is up to you to ensure your shared secret is only made available to authorized users. We recommend you vend your credentials out on demand to authenticated users using an authentication server.

Client Configuration

As noted above for the Native API you can configure some additional properties on your Callstats Client. In JavaScript, you do not have to do this because the Callstats' JavaScript library populates these for you by querying the browser. In this way it sets the OS, OS version, Client Name, and Client Version properties. The App version property is unavailable in the JavaScript API at this time.

Collecting Connection Stats

Last but not least you will need to add connections to your Callstats client. Nothing could be simpler. The parameters for adding the connection are:

  • connection: Your IceLink connection object.
  • localUserId: A unique identifier for your user (supplied by your application).
  • sessionId: Your IceLink session Id.
  • remoteUserId: A unique identifier for the remote user (supplied by your application).
  • deviceId: A unique identifier for the device your application is running on (supplied by your application).
Add Connections
client.addConnection(connection, localUserId, sessionId, remoteUserId);