Google Maps API for Flash Developer Guide

The Google Maps API for Flash provides a new way to add interactive Google Maps to your website, using Adobe's Flash® plugin to display dynamic map content! This API exists as a fully independent alternative to the existing JavaScript Maps API, and provides many of the features of that API while also adding the ability to mix Flash content with Google Maps.

The Google Maps API for Flash is new, so we'd like to hear your feedback. We encourage you to join the Maps API for Flash discussion group to give us feedback.

Audience

This documentation is designed for people familiar with Flash, ActionScript® programming, and object-oriented programming concepts.

This documentation contains three independent tutorials, covering creation of a "Hello World" application in one of the possible Flash development environments:

• Flex SDK Tutorial
• FlexBuilder® Tutorial
• Flash CS3 Tutorial

All new developers should read the tutorial appropriate for their development environment which explains how to write your first Google Maps Flash application.

In addition, this documentation is organized to cover the following key areas:

• Google Maps Flash Basics
• Google Maps Flash Events
• Google Maps Flash Controls
• Google Maps Flash Overlays
• Google Maps Flash Services

Most of the documentation is focused on supporting Flex developers. However, we will strive to keep the documentation usable by all Flash developers.

Introduction

Providing a Flash version of the Google Maps API allows current Flash developers to easily integrate Google Maps into their existing Flash development environments. As well, the Google Maps API for Flash opens up a whole world of interactive possibilities for displaying and using map content for those developers not currently using Flash.

This developer guide assumes you are familiar with Flash development and ActionScript programming. It also does not assume usage of any particular development environment, though we provide tutorials for different development environments.

Note: this guide uses UNIX-like command line examples, and Macintosh screen shots, though usage should not appreciably change for other developers.

Setting Up Your Development Environment

Flash development can take many forms. Some developers/designers author purely within the Flash CS3 application to create and arrange content, and add ActionScript within that framework. Other developers use a full-featured IDE such as Adobe FlexBuilder® to create robust applications with heavy use of ActionScript. Some developers use the freely available Flex SDK® from Adobe and build their applications from the command line. The choice of development environment is up to you.

This documentation will provide tutorials for all three approaches to get you going. However, the code samples within this documentation set will be provided as MXML files, for use within either FlexBuilder, or the free Flex SDK. It is relatively straight-forward to use the ActionScript code embedded within those files directly within Flash CS3.

Obtaining the Interface Library

Developing Flash content that integrates Google Maps requires inclusion of a Google Maps API for Flash interface library within your application code. This library consists of a *.swc file within the lib directory of the Maps API for Flash SDK available at the following URL:

http://maps.googleapis.com/maps/flash/release/sdk.zip

The SDK includes two SWC files: a Flex version for use within FlexBuilder (or with the free Flex SDK), and a non-Flex version for use within Flash CS3. The Flex *.swc is denoted with a _flex suffix in the filename.

These SWC files contain interfaces for all public classes in the Google Maps API for Flash development environment. Compiling your application with this library ensures that it can utilize and communicate with all public functionality of the runtime Google Maps API for Flash library, which is retrieved from Google's servers whenever a client loads your application.

Note that the bulk of the code for actually running your Maps Flash application remains within the separate runtime Google Maps API for Flash library. This allows us to make enhancements, bug fixes, and modifications to the core library functionality without requiring you to recompile your application. Note that if you ever wish to utilize new functionality that requires new interfaces, you will need to download an updated SWC file and recompile your application.

The interface library filename contains a suffix identifying its version number. For example, map_flex_1_7.swc identifies version 1.7 of the Flex interface library, while map_1_7.swc identifies version 1.7 of the Flash interface library. Once you've downloaded the interface library, create a development directory and place that file in the root of that directory.

#
#Create a development directory
#
hostname$ mkdir myflashapp
hostname$ cd myflashapp
#
# Copy the Google Maps API for Flash SDK to the root of your working development directory
#
hostname$ cp ~/sdk.zip .
#
# Unzip the SDK. The SWC interface library is located within the "lib" directory
# Offline ASDoc HTML documentation is available within the "docs" directory
#
hostname$ unzip sdk.zip

Make note of this directory location. You will need it when you need to link to the proper SWC file during development.

Obtaining a Maps API Key

The Google Maps API for Flash, like the Google JavaScript Maps API, requires usage of a freely available developer key. You will need to specify this key within one of three possible locations:

• (For Flex applications) A special configuration file called an MXML declaration
• (For Flash applications) Your ActionScript code (compiling it into the resulting SWF file)
• The containing DOM element in your web page.

Note that the API key is compiled into the SWF file and must match the domain where the SWF file is hosted, which may not necessarily be the location for the hosted HTML file. This document set will show Flex examples defining the API key within the MXML declarations.

Versioning

The Google Maps API for Flash interface library contains the ActionScript interfaces that allow you to communicate with the actual components provided through Google's runtime library. Occasionally, we will make updates to these components "under the hood." As long as the interfaces do not change, you don't need to do anything. The interface SWC file will automatically pick up the latest changes.

If we introduce new functionality and features (and therefore need to update the interfaces), we will also need to update the interface SWC file, which we will provide for download. Such versions will be named according to the version scheme. (For example, the interface library associated with version "1.3" will be named "map_flex_1_3.swc." You will need to download a new version of this interface library before you can make use of these latest features. Make sure you monitor the Google Maps API group or blog to ensure you receive announcements for new versions of the Google Maps API for Flash.

You may set your application to use a hard-coded version of the Maps API for Flash library by setting the Map's version property to a specific version. Note that this is not recommended as you will not benefit from any enhancements or bug fixes to the current implementation.

Tutorials

The following tutorials walk you through creating a sample application using the Google Maps API for Flash in your preferred development environment:

• Flex SDK Tutorial
• FlexBuilder Tutorial
• Flash CS3 Tutorial

You do not need to read all three tutorials to get started, though it may be useful to you to compare the different development processes.