Using the Customer Identification Feature
To integrate the Virtual Earth Platform Customer Identification feature into your Web application, first use your Virtual Earth Platform credentials to request a token. This token contains encrypted information including the end-client’s IP address and your Virtual Earth Platform developer account ID. A token is only valid for the duration specified in the initial request, beginning from the time the token request is made from your server. Set this token in the map control instance that is loaded into the client’s browser and then all requests made to Virtual Earth from your application are identified as requests made by you. Virtual Earth Platform logs these requests and you will be able to view Virtual Earth Platform transaction reports on the Virtual Earth Platform Customer Services site.
These steps are described in further detail in the following sections.
Step 1: Sign up for a Developer Account
Step 2: Add a reference to the Virtual Earth Platform Web Service
Before the Virtual Earth map control is loaded into the end-client’s browser, a token must be retrieved from the Virtual Earth Platform. Virtual Earth Platform provides a secure SOAP API service which contains a GetClientToken method to accomplish this. To use the Virtual Earth Platform web service you need your Virtual Earth Platform credentials, which consist of your developer account ID (found on the Manage Account page of the Virtual Earth Platform Customer Services site) and your developer account password. If you are using ASP .NET to build your application, then in your web application project add a web reference to the Virtual Earth Platform web service. If you are planning on using Java to request a token, depending on your Java Web Service API you may need to create proxy classes before accessing the GetClientToken method. You can find information about this in the Supporting Files for Java topic.
Step 3: Retrieve a Token
The GetClientToken method takes a TokenSpecification object, which contains two pieces of information:
-
The IP address of the client - You can usually extract this information from the client Http Headers using the request.getRemoteHost() method.
-
The length of time the token will be valid - Tokens are issued for a specific time length. You must specify a number of minutes ranging from 15 to 480 (8 hours).
The TokenSpecification Class declaration is below.
[Visual Basic]
Public Class TokenSpecification Inherits System.Object
[C#]
public class TokenSpecification : System.Object
Public Properties
|
Property
|
Description
|
| ClientIPAddress | A string representing the IPAddress to store in the token. Must be a valid IPv4 or IPv6 form. |
| TokenValidityDurationMinutes | An integer representing the number of minutes the token will be valid, beginning from the time the request is made. Maximum allowable value is 480. Minimum allowable value is 15. |
Once you have instantiated the TokenSpecification object, you need to pass it to the GetClientToken method to return a token. The GetClientToken method returns a String, which is the token. The GetClientToken function declaration is below.
[Visual Basic]
Public Function GetClientToken (ByVal specification As TokenSpecification) As String
[C#]
public string GetClientToken (TokenSpecification specification)
The following code gets a token and makes it available for use by the Virtual Earth map control. This code must be called every time the client requests your Web page.
If you are using .NET to build your application, the Visual Basic or C# code can be inserted into the server-side Page_Load event of your ASP .NET Web Application so that it runs before the map control is loaded on the client.
[Visual Basic]
' Place the following code in the Page_Load event of your ASP .NET Web
' application so that it runs before the map control is loaded.
' This code assumes an Imports reference to the Virtual Earth
' Platform Web service.
' Be sure to use an SSL connection to protect your information.
Dim commonService As New CommonServiceSoap()
commonService.Url = "https://common.virtualearth.net/find-30/common.asmx"
commonService.Credentials =
New System.Net.NetworkCredential(
"Virtual Earth Platform Developer Account ID",
"Virtual Earth Platform Developer Account password")
' Create the TokenSpecification object to pass to GetClientToken.
Dim tokenSpec As New TokenSpecification()
' Use the Page object to retrieve the end-client’s IPAddress.
tokenSpec.ClientIPAddress = Page.Request.UserHostAddress
' The maximum allowable token duration is 480 minutes (8 hours).
' The minimum allowable duration is 15 minutes.
tokenSpec.TokenValidityDurationMinutes = 480
' Now get a token from the Virtual Earth Platform service.
Dim clienttoken As String
clienttoken = commonService.GetClientToken(tokenSpec)[C#]
// Place the following code in the Page_Load event of your ASP .NET Web
// application so that it runs before the map control is loaded.
// This code assumes a using reference to the Virtual Earth Platform
// Web service.
// Be sure to use an SSL connection to protect your information.
CommonServiceSoap commonService = new CommonServiceSoap();
commonService.Url = "https://common.virtualearth.net/find-30/common.asmx";
commonService.Credentials =
new System.Net.NetworkCredential(
"Virtual Earth Platform Developer Account ID",
"Virtual Earth Platform Developer Account password");
// Create the TokenSpecification object to pass to GetClientToken.
TokenSpecification tokenSpec = new TokenSpecification();
// Use the Page object to retrieve the end-client’s IPAddress.
tokenSpec.ClientIPAddress = Page.Request.UserHostAddress;
// The maximum allowable token duration is 480 minutes (8 hours).
// The minimum allowable duration is 15 minutes.
tokenSpec.TokenValidityDurationMinutes = 480;
// Now get a token from the Virtual Earth Platform service.
string clienttoken = commonService.GetClientToken(tokenSpec);If you are using Java and Axis proxy classes to build your application, the code will be similar to the code below. The classes used in this code sample are detailed in the Supporting Files for Java topic.
[Java]
tokenSpec = new TokenSpecification();
commonStub = new CommonServiceSoapStub(new
URL("https://common.virtualearth.net/find-30/common.asmx"), null);
env = (Context) new InitialContext().lookup("java:comp/env");
UserName = (String) env.lookup("UserName");
Password = (String) env.lookup("Password");
commonStub.setUserName(UserName);
commonStub.setPassword(Password);
tokenSpec.setClientIPAddress(clientIP);
//The maximum allowable token duration is 480 minutes (8 hours).
tokenSpec.setTokenValidityDurationMinutes(480);
//Retrieve the token.
String token = commonStub.getClientToken(tokenSpec); Step 4: Set the Token in the Map Control
After the token has been retrieved from the Virtual Earth Platform Web service, it must be passed to the client and set for every VEMap instance. You can pass the token to the client using any of a variety of web methods, including adding it as a hidden field, or putting it in the query string.
If you are building your application using ASP .NET, you can use the following code on the client to retrieve the clienttoken server variable set in the Visual Basic .NET or C# code samples in Step 2.
[JavaScript]
// Retrieve the clienttoken variable from server-side code.
var token = "<%=clienttoken %>";
After you have passed the token string to the client, the SetClientToken method of the VEMap class is provided to set the token on the VEMap instance.
[JavaScript]
VEMap.SetClientToken(token);
Setting the token before you load the map or make any other Virtual Earth requests ensures that every request sent to Virtual Earth is identified.
[JavaScript]
// Set the token before loading the map or making any other
// Virtual Earth requests.
var map = new VEMap(‘mymap’);
map.SetClientToken(token);
map.LoadMap();
Once the token is set, all transaction based calls will be logged against your Virtual Earth Platform Developer Account.
Step 5: Handle Token Expiration and Error Events
Every time a Virtual Earth map control request is made, the token that was set is passed to the server for identification and validation. There are two callback events that can be used to catch token errors. The first is the ontokenerror event. This event occurs when a map control request is made with a token that is not a valid Virtual Earth Platform token. The second is the ontokenexpire event and it occurs when a map control request is made with an expired token. A client token is valid for the duration specified in the request, beginning from the time the request for the token was made to the Virtual Earth Platform Web service. Once the token expires, you will want to alert the end-client that their session has expired and that their browser should be refreshed. To catch these events, use the VEMap.AttachEvent Method. The following code sample shows how to catch token expire and token error events.
[JavaScript]
// Attach token expired and token error events.
var map = new VEMap(‘mymap’);
map.AttachEvent('ontokenexpire', MyHandleTokenExpire);
map.AttachEvent('ontokenerror', MyHandleTokenError);
function MyHandleTokenExpire()
{
// insert code here to handle token expiration
}
function MyHandleTokenError()
{
// insert code here to handle token errors
}
