Introduction

This developer guide provides quick tutorials to start using the GermaniumWeb API. Please look at the API documentation for complete reference.

Contents

Audience

This guide is written for people interested to develop a web application that uses the GermaniumWeb API. If you are a web application developer, you are at the correct place to start developing!

You will write code in JavaScript when using GermaniumWeb API. We assume that you are familiar with JavaScript programming.

How it works

File:How_it_works.jpg

  1. You (Web Developer in the diagram above) write a web application that uses GermaniumWeb to show a 3D scene. Your application can be as simple as a single HTML file (index.html) that is hosted at a web server (www.example.com).
  2. Your HTML file has a <script> tag that tells the browser to fetch the GermaniumWeb JavaScript API (JSAPI) from api.germanium3d.com. The API provides functions that you call in your application.
  3. When a User views your web application, the JSAPI checks if the GermaniumWeb plugin is installed on his/her computer.
    • If the GermaniumWeb plugin is not installed, the JSAPI will show a web page with a link to download the plugin.
    • If the GermaniumWeb plugin is installed, the JSAPI will use it to show the 3D scene you programmed in your application.

Installing the plugin

Your computer should meet the minimum system requirements. The GermaniumWeb plugin is currently available only for Microsoft Windows (XP, Vista, and 7). Supported browsers are:

Follow these steps to start writing your application:

  1. Download and install the plugin.
  2. Sign up for a GermaniumWeb API key.
  3. Start writing your web application using the GermaniumWeb API.

Uninstalling the plugin

Should you decide to uninstall GermaniumWeb plugin from your computer, you can do so in 2 ways:

Getting started with the API

You can use the following HTML as your starting point.

Source: Introduction example

<html>
<head>
	<title>GermaniumWeb Example - Introduction</title>
	<!-- *** Replace the key below with your own API key.
	         You can get one from http://www.germanium3d.com/code/signup ***  -->
	<script src="http://api.germanium3d.com/?v=1.5&key=your_API_key"></script>
 
	<script>
var germ = null;
 
function Init() {
        try 
        {
               // Check if GermaniumWeb API was successfully 
               // retrieved by checking if "Germanium" exists.
               void(Germanium); 
        }
        catch (e)
        {
               alert("API retrieval failed. Error message: [" + e + "]");
               return;
        }
	Germanium.CreateInstance("myGerm", InitSuccessCallback, InitFailureCallback);
}
 
function InitSuccessCallback(webControl) {
	// Save the WebControl object. Now the rest of the webapp 
	// can use it through the 'germ' variable.
	germ = webControl; 
}
 
function InitFailureCallback(message, code) {
	alert("Germanium initialization failed: " + message +
		"; error code: " + code);
}
	</script>
</head>
 
<body onload="Init();">
	<b>GermaniumWeb Example - Introduction</b>
	<br>
	<div id="myGerm" style="width:600px; height:400px;"></div>
</body>
</html>

There are 4 steps to note in the code:

  1. Request the API for use.
  2. Create a div container for the plugin.
  3. Write a JavaScript function to create an instance of the plugin.
  4. Call the plugin creation function when the web page finishes loading.

1. Request the API for use

	<!-- *** Replace the key below with your own API key.
	         You can get one from http://www.germanium3d.com/code/signup ***  -->
	<script src="http://api.germanium3d.com/?v=1.5&key=your_API_key"></script>

The example above requests specifically for API version 1.5 by specifying v=1.5. If you do not specify an API version, your web page will always use the newest version. This will force visitors to your web page to upgrade their plugin more often than necessary, so we recommend specifying an API version.

2. Create a div container for the plugin

You need to provide an empty div to hold the GermaniumWeb plugin on your web page.

<div id="myGerm" style="width:600px; height:400px;"></div>
Warning: Watch out for this gotcha.

3. Write a JavaScript function to create an instance of the plugin

The function below first checks that the GermaniumWeb API has been successfully retrieved, and then creates an instance of the plugin.

function Init() {
        try 
        {
               // Check if GermaniumWeb API was successfully 
               // retrieved by checking if "Germanium" exists.
               void(Germanium); 
        }
        catch (e)
        {
                alert("API retrieval failed. Error message: [" + e + "]");
                return;
        }
        Germanium.CreateInstance("myGerm", InitSuccessCallback, InitFailureCallback);
}

Note that GermaniumWeb needs the id of the container div you provided in the previous step ("myGerm" in the example).

Germanium.CreateInstance() is an asynchronous function. It will take anywhere from 100ms to a few seconds to execute, depending on the speed of your machine. When it is done, it will call InitSuccessCallback if successful, or InitFailureCallback if not.

function InitSuccessCallback(webControl) {
	// Save the WebControl object. Now the rest of the webapp 
	// can use it through the 'germ' variable.
	germ = webControl; 
}
 
function InitFailureCallback(message, code) {
	alert("Germanium initialization failed: " + message +
		"; error code: " + code);
}
Warning: You can only use the plugin (represented by the WebControl object) after InitSuccessCallback has been called.

InitFailureCallback should expect 2 parameters:

  1. a string that contains error message and
  2. an error code (see InitErrorCodes in API documentation for list of error codes).

4. Call the plugin creation function when the web page finishes loading

<body onload="Init();">

Troubleshooting

If your code does not seem to work, here are a few tips that may help:

Retrieved from "http://www.germanium3d.com/code/Docs"

This page has been accessed 5,393 times. This page was last modified on 18 August 2015, at 08:53.


Developers


Main

API Key Registration

Developer Guide
- Introduction
- Buildings
- Point Placemarks
- Line & Polygon      PlacemarksUpdated
- Model Placemarks New
- HTMLBoxes New
- Eye Control
- Clip Planes
- Events
- Coordinate System
- Navigation Modes
- Options

API Documentation

Examples
- Applications Gallery
- Hello Germanium
- Interactive samples

More Resources
- API Release Notes
- Developer FAQ
- "A Beginner's Guide" slides
- Training Materials
- Icon Gallery
- Sample Buildings
- BBL Tree

Report Bugs