Debugging the Google Earth Plugin

Unfortunately, as HyperCities depends on Google Earth, it’s not uncommon to encounter issues. The Google Earth plugin already taxes most computers, and its API is somewhat unstable. The purpose of this section will be to help with debugging problems with HyperCities and the Google Earth API.

Most computers do not have the Google Earth plugin installed; sometimes, HyperCities is the first website someone will visit that requires them to download the Google Earth plugin. It’s not unlikely that someone who uses HyperCities a lot will have a version that is different from someone who is visiting for the first time. Therefore, if you are having students use HyperCities in class, they may have a different version from you. To check this, visit this page: http://www.google.com/earth/explore/products/plugin.html. This will display the version number of the Google Earth plugin installed on the user’s computer. On top of this, the Earth plugin does not always update itself, so you may not realize that two computers have different versions.

This matters because the API can change in subtle but significant ways between versions. Because of this, it is not uncommon for HyperCities to break completely when a new version of the Google Earth plugin is released. Therefore, it makes sense for a developer or tech support person to regularly check for new versions of the Google Earth plugin, and to check for problems.

Some problems we have encountered

Here is a brief list of problems we have encountered with regards to the Google Earth plugin. This may provide some helpful places to start looking when you encounter problems.

Event firing

Google Earth’s practices for handling and dispatching events from the browser has changed from version to version. We have had HyperCities lock up because the GE plugin started to re-dispatch events that it received from the browser, which created an infinite loop of propagating events. If you experience lock-ups, then, it makes sense to try trapping events that are being dispatched to the plugin and see if they are being returned to the browser, or triggering other events that are re-dispatched to the plugin.

The initialization process

Given how resource-intensive the plugin’s initialization process is, it’s possible that the plugin can be sent calls while it is still in the initialization process. These can return “Error calling method on NPObject” calls (which mean that the plugin caused an error but didn’t return a more specific message), which cause JavaScript functions to fail. It always makes sense to check if the plugin has been initialized in cases like these.

Sticky objects

While Google Earth exposes an API for adding, enumerating, and removing objects on the globe, these do not always work. We have had some problems with what we’ve called “sticky maps” and “sticky KMLs”--in other words, trouble removing KML and image overlays in once we add them in a few small, reproducible cases. While we have been able to resolve some of these issues, we have not been able to resolve all of them, because identifying why they happens is difficult. Therefore, you may see similar problems as the Earth plugin API changes.