Pictometry® IPA Quick Start Guide

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 byany means, electronic or mechanical, including photocopying, recording, or otherwise, without the priorwritten permission of Pictometry International Corporation.Pictometry® is a trademark of Pictometry International Corp. All other brands or products are the trademarksor registered trademarks of their respective holders.Pictometry International Corporation100 Town Centre DriveRochester, NY 14623Printed in the United States of AmericaDocumentation Version 1.0 [update]July 2012IPA Quick Start Guideii

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

OverviewClient requirementsTier 1 – fully supportedThe 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 higherTier 2 – partially supportedThe following browsers are supported using a compatibility feature of the IPA JavaScript library to emulatecross-domain messaging. While every effort has been made to ensure it is fully compatible, there may becertain circumstances under which it does not work properly. To ensure full compatibility use one of thebrowsers listed under Tier 1 above.• Internet Explorer 7• Firefox 3.0 - 3.5• Chrome 15 or earlier• Safari 4Internet Explorer 6 is not supported for use with IPA.Web application development environmentTo 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 signedhash using the HMAC (hash-based message authentication code) algorithm. For more informationabout the HMAC algorithm, see the IETF RFC (Request for Comments) 2104 document.Recommended languagesThe 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 languagesThese 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. Youwill have to verify HMAC support before using a different language.IPA Quick Start Guide 3

Embedding the IPAEmbedding the IPAThis section describes what you need to do to embed the IPA in your client environments. It involves 4 basicelements:1. Code to generate the digital signature for the IPA Load URL2. Adding the IPA JavaScript Library3. Adding the IPA iframe4. JavaScript code to initialize and interact with the IPAWeb page requirementsMake 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 IPAKeys and URLs neededTo generate the web page code, you need the following items (already provided by Pictometry):• API Key• Secret Key• IPA Load URL• IPA JavaScript Library URLGenerating the digital signatureEvery page on which you want to embed the IPA will need to generate a new signed IPA Load URL using thefollowing information.• url: The IPA Load URL• apikey: The API Key• secretkey: The Secret Key• timestamp: The current time in GMT as a unix timestampThis URL is then used to create the digital signature using the HMAC algorithm. This signature is appendedto 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// generate the hash$signature = hash_hmac('md5', 'mymessage', 'mysecretkey');C# Example:// generate the hashSystem.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 stringstring signature = BitConverter.ToString(hash).Replace("-", "").ToLower();Loading the JavaScript LibraryTo load the Pictometry JavaScript library, you’ll need to add a script element for the JavaScript Library URL toeach web page for which you want the IPA to be available.The following example shows the script element you need to add.Example:My ApplicationAdding the iframe elementYou’ll use an iframe element to load the IPA in your web page. You’ll need to add an iframe element, styledas needed, to each page where you would like the IPA to be embedded. The iframe element needs to havethe following attributes:• src: The signed IPA Load URL as described above. The app_id parameter also needs to be appendedso 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 iscommunicating with the correct iframe.• &app_id=[iframe id]PHP Example:

Embedding the IPAASP.NET Example 2: (dynamically loaded iframe src – must be called AFTER the iframe element iscreated)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 IPAvar iframe = document.getElementById('pictometry_ipa');iframe.setAttribute('src', '');Note: Working code examples for both PHP and C#/ASP.NET are available in the examples directory of thearchive this document was provided with.IPA Quick Start Guide 8

Communicating with the IPACommunicating with the IPARefer to the Integrated Pictometry Analytics API Guide for specific calls and events available to you.Initial SetupBefore any API calls can be made, a communication channel needs to be setup between the IPA and the hostapplication. The first part of this setup happens during the PictometryHost object instantiation before the IPAapp is loaded into the iframe. Once the IPA has completed initializing, a call is made to the function that youassigned 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 callAll API calls are made using methods of the PictometryHost class instance. This class is available as soonas the IPA JavaScript has been loaded, but will not be completely ready for use until AFTER the ready() eventoccurs.Example:Here’s an example of an API call that sets the starting location of the map by using a method calledsetCenter().ipa.setCenter(43.152139, -77.580298);Retrieving data from the IPAOn some occasions it will be necessary to retrieve information from the IPA (current location, measurementresult, 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 IPANote that each callback will be sent different parameters. The specific parameters for each callback aredescribed in the Integrated Pictometry Analytics API Guide.IPA EventsListening for eventsOnce 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 tothe 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

TroubleshootingTroubleshootingYou see a 'Login Failed' message when loading the IPAPlease check the following in order:1. Ensure you are using the correct API Key and Secret Key. The keys should exactly match what wasgiven to you by Pictometry. Also make sure that you have not swapped the keys (using API Key forSecret Key and vice versa).2. Verify that the signature is being generated properly. See the section titled ‘Validating your HMAChash’ 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 triggeredPlease check the following in order:1. Verify that the host application is served from the URL you provided to Pictometry prior to receivingyour API Key/Secret Key set. The URL that Pictometry has on file should be listed in the documentthat contains your API Key and Secret Key. The keys are tied to a specific domain and will not workfor any other domain. If you are using a port other than 80 for http or 443 for https, please makesure 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 theiframe or it does not match.5. Verify that you are using a supported browser.IPA Quick Start Guide 11