Integrated Pictometry Analytics Quick Start Guide. July 2012

Integrated Pictometry Analytics Quick Start Guide July 2012

Copyright 2012 Pictometry International Corp. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system or transmitted, in any form or by any means, electronic or mechanical, including photocopying, recording, or otherwise, without the prior written permission of Pictometry International Corporation. Pictometry is a trademark of Pictometry International Corp. All other brands or products are the trademarks or registered trademarks of their respective holders. Pictometry International Corporation 100 Town Centre Drive Rochester, NY 14623 Printed in the United States of America Documentation Version 1.0 [update] July 2012 IPA Quick Start Guide ii

Contents About this guide... 1 Related documentation... 1 Overview... 1 Client requirements... 2 Tier 1 fully supported... 2 Tier 2 partially supported... 2 Web application development environment... 2 Recommended languages... 2 Untested languages... 2 Embedding the IPA... 4 Web page requirements... 4 Keys and URLs needed... 4 Generating the digital signature... 4 Validating the HMAC signature... 5 Loading the JavaScript Library... 6 Adding the iframe element... 6 Initializing IPA Communication... 7 Communicating with the IPA... 9 Initial Setup... 9 Simplified overview of the startup sequence for an IPA:... 9 Making an API call... 9 Retrieving data from the IPA... 9 IPA Events... 10 Listening for events... 10 Troubleshooting... 11 IPA Quick Start Guide iii

About this guide About this guide This Quick Start Guide describes what you need to do to start using the Integrated Pictometry Analytics (IPA) API so your users can use Pictometry imagery and tools within your own web applications as quickly as possible. It covers application development requirements, [finish]. This guide is intended for Software Developers who are already familiar with server-side and client-side web development and specifically JavaScript, HTML, and server-side implementation languages. It assumes that you are familiar with at least one of these programming languages: PHP, Java, C#, VB.NET, Python, Perl, or Ruby. If you find errors in this guide, or if you have comments about it, we d like to know. Please email us at documentation@pictometry.com. Related documentation Along with this guide, you should have received the Integrated Pictometry Analytics API Guide, which describes the API calls and events, the key pair file, as well as an examples directory. Overview The IPA is a web component that can be integrated with your web application by using JavaScript and iframes. The IPA is loaded as part of your web page and makes calls to Pictometry via the IPA JavaScript Library. The steps for integrating the IPA on your web page are covered in this document. Once you ve set up your web application to load the IPA on client computers, the IPA will communicate with the Pictometry API directly so your users can use Pictometry imagery and tools in your web application. IPA Quick Start Guide 1

Overview Client requirements Tier 1 fully supported The following browsers are recommended for use with IPA. Internet Explorer 8 or higher Firefox 3.6 or higher Chrome 16 or higher Safari 5 or higher Tier 2 partially supported The following browsers are supported using a compatibility feature of the IPA JavaScript library to emulate cross-domain messaging. While every effort has been made to ensure it is fully compatible, there may be certain circumstances under which it does not work properly. To ensure full compatibility use one of the browsers listed under Tier 1 above. Internet Explorer 7 Firefox 3.0-3.5 Chrome 15 or earlier Safari 4 Internet Explorer 6 is not supported for use with IPA. Web application development environment To use the IPA, your web applications must meet these requirements: They must support the use of iframes. (See Adding the iframe element on page 6.) They must be developed with a recommended language one that supports the generation of a signed hash using the HMAC (hash-based message authentication code) algorithm. For more information about the HMAC algorithm, see the IETF RFC (Request for Comments) 2104 document. Recommended languages The following languages have been tested and are known to generate an HMAC signed hash correctly: PHP 5.1.2 or higher (hash_hmac) Java 1.4.2 or higher (HMAC-MD5 Example).NET Framework 2.0 or higher (HMAC) Untested languages These languages are untested, but should work: Python 2.2 or higher (hmac) IPA Quick Start Guide 2

Overview Perl (using Digest::HMAC from CPAN) Ruby (using ruby-hmac gem from rubyforge) Languages other than those listed above might also work, but we cannot confirm if they support HMAC. You will have to verify HMAC support before using a different language. IPA Quick Start Guide 3

Embedding the IPA Embedding the IPA This section describes what you need to do to embed the IPA in your client environments. It involves 4 basic elements: 1. Code to generate the digital signature for the IPA Load URL 2. Adding the IPA JavaScript Library 3. Adding the IPA iframe 4. JavaScript code to initialize and interact with the IPA Web page requirements Make sure that each web application page where you want to use the IPA meets these requirements: includes a script element that links to the Pictometry JavaScript library generates a new HMAC signature for each page load contains an iframe element which will be used as the location for the IPA Keys and URLs needed To generate the web page code, you need the following items (already provided by Pictometry): API Key Secret Key IPA Load URL IPA JavaScript Library URL Generating the digital signature Every page on which you want to embed the IPA will need to generate a new signed IPA Load URL using the following information. url: The IPA Load URL apikey: The API Key secretkey: The Secret Key timestamp: The current time in GMT as a unix timestamp This URL is then used to create the digital signature using the HMAC algorithm. This signature is appended to the end of the URL to create the signed URL that is used as the src attribute for the iframe. PHP Example: IPA Quick Start Guide 4

Embedding the IPA $apikey = '12345'; $secretkey = '987654321'; $loadurl = 'http://some.pictometry.com/url/load.php'; $url = $loadurl. '?apikey='. $apikey. '&ts='. time(); $signature = hash_hmac('md5', $url, $secretkey); // final signed url $signedurl = $url. '&ds='. $signature; C# Example: using System; using System.Security.Cryptography; string apikey = "12345"; string secretkey = "987654321"; string loadurl = "http://some.pictometry.com/url/load.php"; // create timestamp TimeSpan span = (DateTime.UtcNow - new DateTime(1970,1,1,0,0,0,DateTimeKind.Utc)); long ts = (long) Math.Floor(span.TotalSeconds); // create the url string url = loadurl + "?apikey=" + apikey + "&ts=" + ts; // generate the hash System.Text.ASCIIEncoding encoding = new System.Text.ASCIIEncoding(); HMACMD5 hmac = new HMACMD5(encoding.GetBytes(secretKey)); byte[] hash = hmac.computehash(encoding.getbytes(url)); // convert hash to digital signature string string signature = BitConverter.ToString(hash).Replace("-", "").ToLower(); // create the signed url string signedurl = url + "&ds=" + signature; Validating the HMAC signature After you ve generated your HMAC hash signature, you ll need to test it to be sure it works. Use these values to test the signature: key: 'mysecretkey' message: 'mymessage' These values will create this hash signature: 58af6f92bf1e5f42deff3e986b10f093 If you don t get this result, then the algorithm isn t working. Re-check your code, fix any errors, and test the hash signature again, until you are sure it is working. Once the hash is working, no further validation is needed. For PHP and C#, use the following code to test your HMAC hash. PHP Example: IPA Quick Start Guide 5

Embedding the IPA // generate the hash $signature = hash_hmac('md5', 'mymessage', 'mysecretkey'); C# Example: // generate the hash System.Text.ASCIIEncoding encoding = new System.Text.ASCIIEncoding(); HMACMD5 hmac = new HMACMD5(encoding.GetBytes("mysecretkey")); byte[] hash = hmac.computehash(encoding.getbytes("mymessage")); // convert hash to digital signature string string signature = BitConverter.ToString(hash).Replace("-", "").ToLower(); Loading the JavaScript Library To load the Pictometry JavaScript library, you ll need to add a script element for the JavaScript Library URL to each web page for which you want the IPA to be available. The following example shows the script element you need to add. Example: <head> <title>my Application</title> <!-- include the client side script from pictometry --> <script type="text/javascript" src="http://some.pictometry.com/url/embed/host.php"/></script> </head> Adding the iframe element You ll use an iframe element to load the IPA in your web page. You ll need to add an iframe element, styled as needed, to each page where you would like the IPA to be embedded. The iframe element needs to have the following attributes: src: The signed IPA Load URL as described above. The app_id parameter also needs to be appended so the IPA knows the iframe that it is communicating with. id: The unique id of the iframe. This is required as it is used by the IPA for communication. The signed IPA Load URL also needs to have the iframe id appended to it. This ensures that the IPA is communicating with the correct iframe. &app_id=[iframe id] PHP Example: <iframe id="pictometry_ipa" src="<?php echo $signedurl;?>&app_id=pictometry_ipa"></iframe> IPA Quick Start Guide 6

Embedding the IPA ASP.NET Example: <iframe id="pictometry_ipa" src="<% Response.Write(signedUrl) %>&app_id=pictometry_ipa"></iframe> Initializing IPA Communication Before the IPA is loaded in the iframe, a new instance of PictometryHost() needs to be created to setup the communication channel to the IPA. This class requires two parameters to initialize: iframeid: The HTML element id of the iframe the IPA will be loaded into. loadurl: The IPA Load URL (Pictometry supplied). The second part of the process is setting up the ready() function. This function is called when the IPA has finished initializing and is ready for use. This function can do whatever you need it to, but typically this is the place to set a starting location, add event listeners, or other actions that depend on the IPA being available. Important: The initialization code below needs to be executed BEFORE the iframe loads. The easiest solution is to just include the script in the head tag so it executes immediately on page load (Example 1). Alternatively, the iframe src can be set dynamically after the PictometryHost instance has been created (PHP Example 2 and ASP.NET Example 2). Example 1: (placed in head tag) <script type="text/javascript"> var ipa = new PictometryHost('pictometry_ipa', 'http://some.pictometry.com/url'); ipa.ready = function() { ipa.addlistener( 'someevent', function( param1, param2 ) { // do something here } ); ipa.setcenter(43.152139, -77.580298); }; </script> PHP Example 2: (dynamically loaded iframe src must be called AFTER the iframe element is created) <script type="text/javascript"> var ipa = new PictometryHost('pictometry_ipa', 'http://some.pictometry.com/url'); ipa.ready = function() { ipa.addlistener( 'someevent', function( param1, param2 ) { // do something here } ); ipa.setcenter(43.152139, -77.580298); }; // set the iframe src to load the IPA var iframe = document.getelementbyid('pictometry_ipa'); iframe.setattribute('src', '<?php echo $signedurl;?>'); </script> IPA Quick Start Guide 7

Embedding the IPA ASP.NET Example 2: (dynamically loaded iframe src must be called AFTER the iframe element is created) <script type="text/javascript"> var ipa = new PictometryHost('pictometry_ipa', 'http://some.pictometry.com/url'); ipa.ready = function() { ipa.addlistener( 'someevent', function( param1, param2 ) { // do something here } ); ipa.setcenter(43.152139, -77.580298); }; // set the iframe src to load the IPA var iframe = document.getelementbyid('pictometry_ipa'); iframe.setattribute('src', '<% Response.Write(signedUrl) %>'); </script> Note: Working code examples for both PHP and C#/ASP.NET are available in the examples directory of the archive this document was provided with. IPA Quick Start Guide 8

Communicating with the IPA Communicating with the IPA Refer to the Integrated Pictometry Analytics API Guide for specific calls and events available to you. Initial Setup Before any API calls can be made, a communication channel needs to be setup between the IPA and the host application. The first part of this setup happens during the PictometryHost object instantiation before the IPA app is loaded into the iframe. Once the IPA has completed initializing, a call is made to the function that you assigned to the PictometryHost.ready property. This function is where any initial API calls should be made (for location, etc). Simplified overview of the startup sequence for an IPA: Making an API call All API calls are made using methods of the PictometryHost class instance. This class is available as soon as the IPA JavaScript has been loaded, but will not be completely ready for use until AFTER the ready() event occurs. Example: Here s an example of an API call that sets the starting location of the map by using a method called setcenter(). ipa.setcenter(43.152139, -77.580298); Retrieving data from the IPA On some occasions it will be necessary to retrieve information from the IPA (current location, measurement result, etc.). To accomplish this task, certain API methods require that a callback function be provided.. Example: Get the center of the currently displayed image. ipa.getcenter( function(latitude, longitude) { alert(latitude + " : " + longitude); } ); IPA Quick Start Guide 9

Communicating with the IPA Note that each callback will be sent different parameters. The specific parameters for each callback are described in the Integrated Pictometry Analytics API Guide. IPA Events Listening for events Once the IPA has finished loading, the ready() function is automatically called and the IPA is ready to use. To listen for events from the IPA, your web application must pass the event name and a callback function to the addlistener()method. This should be done in the ready()function. Example: ipa.ready = function() { ipa.addlistener( 'someevent', function( param1, param2 ) { // do something here } ); }; The Integrated Pictometry Analytics API Guide describes all events available to you. IPA Quick Start Guide 10

Troubleshooting Troubleshooting You see a 'Login Failed' message when loading the IPA Please check the following in order: 1. Ensure you are using the correct API Key and Secret Key. The keys should exactly match what was given to you by Pictometry. Also make sure that you have not swapped the keys (using API Key for Secret Key and vice versa). 2. Verify that the signature is being generated properly. See the section titled Validating your HMAC hash above. 3. The IPA Load URL does not match what is saved for the IPA User (i.e. http:// vs. https://) PictometryHost calls do not seem to do anything or PictometryHost events are never triggered Please check the following in order: 1. Verify that the host application is served from the URL you provided to Pictometry prior to receiving your API Key/Secret Key set. The URL that Pictometry has on file should be listed in the document that contains your API Key and Secret Key. The keys are tied to a specific domain and will not work for any other domain. If you are using a port other than 80 for http or 443 for https, please make sure that the URL given to Pictometry reflects this. 2. The iframe id has not been set. 3. The iframe id has not been passed to PictometryHost on instantiation or does not match. 4. The iframe id has not been passed to in the signed IPA Load URL in the app_id parameter in the iframe or it does not match. 5. Verify that you are using a supported browser. IPA Quick Start Guide 11