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 Token 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 which contains a GetClientToken method to accomplish this. To use the Virtual Earth Platform Token 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. Microsoft provides a staging environment to test your application and a production environment to use once you have become a licensed customer.
Staging Environment
The Virtual Earth Platform staging environment is separate from but complementary to the production services you use when your application goes live. You can use the staging environment to prototype, develop, and test new applications.
Note The staging environment is not scaled for the extraordinary volumes that the production environment is designed to provide. Any application stress or performance testing is limited to a certain number of requests per second and time of day.
The Virtual Earth Platform Token service URL in the staging environment is https://staging.common.virtualearth.net/find-30/common.asmx.
Production Environment
The Virtual Earth Platform production environment is fully scaled for all Virtual Earth Platform customers. You use this environment when your application is made available to the public through the Internet, including live, beta, evaluation, and prerelease types of applications. To access the Production environment, you must be a licensed customer. Contact the Microsoft Virtual Earth Licensing Team for more information.
Note Activity in the production environment is billable. For more information about Billable Transactions, see the Billable Transactions section below.
The Virtual Earth Platform Token service URL in the production environment is https://common.virtualearth.net/find-30/common.asmx.
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 Staging or Production Token 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 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 Token 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 Token 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
// Token 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 Token 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 Token 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, load the staging or production map control and use the SetClientToken method of the VEMap class to set the token on the VEMap instance.
The Staging environment reference to the map control is:
|
<script type="text/javascript" src="http://staging.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2"></script> |
The Production environment reference to the map control is:
|
<script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2"></script> |
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 transactions are 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 Token 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
} |