SDK Embedding#

Required roles: AIS Map SDK Access — Roles
Base endpoint: https://ais-map.ibosoft.net.tr/ais-map-loader.js
Reference documents: none
Attribution: show ibonav.aero wherever this data is displayed
Data sources: see the ibonav.aero User Guide; each layer's source is shown in the map's attribution
Last updated: 18 OCT 2026

Depending on your use, the original data sources may also need to be credited.

This page embeds the complete ibonav.aero Interactive Map. If you only need the map tiles or the aeronautical data (to show them in your own map or application), see the Tile Server (Layer Lists) and Geo Server sections instead.

SDK embedding builds the ibonav.aero Interactive Map directly in your own page, in a <div> you choose. Unlike frame embedding, the map runs inside your page: you can change its defaults with overrides, reach the OpenLayers map object and add your own layers and interactions on top of it.

One script, ais-map-loader.js, loads all SDK modules and the stylesheet. The map needs OpenLayers on the page and an API access token from your server.

---

1. Get an access token on your server#

1. On your account at https://auth.ibosoft.net.tr, the responsible person needs the AIS Map SDK Access (ais-data:map-sdk) role. In the ibonav.aero - API & Data Access card they create a personal API token (ibp_…). Keep it on your server only.

2. Your server exchanges it for a 1-hour access token:

   POST https://auth.ibosoft.net.tr/api/gateway/token
   Authorization: Bearer ibp_...
   

   { "success": true, "token": "...", "expires_in": 3600, "roles": [] }
   

3. Give your page an endpoint of your own (e.g. /my-server/ais-map-token) that returns { token, expires_in }.

Details of tokens and roles: Authorization.

2. Add the map to your page#

<!-- OpenLayers (window.ol) — must be loaded BEFORE the loader -->
<link rel="stylesheet" href="https://ais-map.ibosoft.net.tr/openlayers/ol.css">
<script src="https://ais-map.ibosoft.net.tr/openlayers/ol.js"></script>

<div id="map" style="width: 100%; height: 600px;"></div>

<script>
  // 1. Overrides — defined BEFORE the loader
  window.AisMapConfigOverrides = {
    // Required: returns Promise<{ token, expires_in }> from your own server
    getAccessToken: function () {
      return fetch('/my-server/ais-map-token', { method: 'POST' })
        .then(function (r) { return r.json(); });
    },
    defaultDim: 30,
    addDefaultLayers: ['atsairspace_ctr', 'navaid_navaids']
  };

  // 2. Called once, after every SDK module has loaded
  window.AisMapOnReady = function () {
    AisMap.init({ target: 'map' });
  };
</script>

<!-- 3. The loader: all SDK modules + CSS -->
<script src="https://ais-map.ibosoft.net.tr/ais-map-loader.js"></script>

• OpenLayers: the SDK uses the full OpenLayers build as the global window.ol (the map itself uses OpenLayers 10.8.0, served at https://ais-map.ibosoft.net.tr/openlayers/). You may load your own copy instead if it provides the same global.
• Token: the SDK adds the token to every data request and calls getAccessToken() again about 5 minutes before it expires, or when a request is rejected. Without getAccessToken no data is loaded and the console shows [AisMap] SDK mode needs AisMapConfigOverrides.getAccessToken().
• Roles: in SDK embedding roles are always off. Only the role locks that have an override (Surveillance, ATC broadcasts) can be opened; Google Earth / HGM base maps and the NATO charts stay locked.
• Query strings are read from your page's address (window.location.search). Avoid using the same parameter names for your own purposes.

3. Wait for the map#

The loader loads the modules asynchronously and calls AisMapOnReady once, after all of them have run. Code placed right after the loader tag cannot assume the map is ready. Put every use of AisMap inside AisMapOnReady, or behind a promise it resolves:

<script>
  var aisMapReady = new Promise(function (resolve) {
    window.AisMapOnReady = function () {
      AisMap.init({ target: 'map' });
      resolve(AisMap.getMap());
    };
  });
</script>
<script src="https://ais-map.ibosoft.net.tr/ais-map-loader.js"></script>

<script>
  aisMapReady.then(function (olMap) {
    // olMap is the ol.Map instance: add your own layers, listen to events …
    olMap.on('moveend', function () {
      console.log(olMap.getView().getCenter());
    });
  });
</script>

---

API#

init options:

---

Overrides#

window.AisMapConfigOverrides changes the SDK defaults without touching any SDK file. Define it before the loader. Unknown fields and wrong value types are ignored.

Access#

Map view#

Layers#

overrideDefaultLayers, addDefaultLayers and defaultBaseMap can be combined: first everything is turned off, then the listed layers are turned on.

Display#

Surveillance (ADS-B)#

ATC broadcasts#

Feature listing#

Server addresses#

Normally not needed; all default to the ibonav.aero servers.

Order of precedence#

AisMap.init(options)            highest (centre / zoom)
query strings                   one-time, not saved
AisMapConfigOverrides           your page
viewer's saved preferences      layers, dimmer, projection, last position
SDK defaults                    lowest

For layers: overrideDefaultLayers and defaultBaseMap apply only to layers the viewer has not changed; a saved choice wins. addDefaultLayers (and mapLayersAdd) always turn their layers on, also over a saved choice. When the viewer resets the layer settings, the saved choices are cleared and the overrides apply in full again.

---

ATC data#

Surveillance (ADS-B) and live ATC broadcasts come through the same access token. The person who created the personal token needs the matching developer role as well:

Then turn off the map's own role locks, since access is checked by the server from the token:

window.AisMapConfigOverrides = {
  getAccessToken: function () { /* … */ },
  surveillanceRequiredRoles: [],
  atcChannelsRequiredRoles: []
};

D-ATIS and DCL in the aerodrome ATC tab need no extra role.

---

Examples#

Start empty, satellite base map, a few layers:

window.AisMapConfigOverrides = {
  getAccessToken: getToken,
  overrideDefaultLayers: true,
  defaultBaseMap: 'web_esri_imagery',
  addDefaultLayers: ['navaid_navaids', 'atsairspace_ctr', 'atsairspace_tma']
};

Fixed view centred on Istanbul, no projection change, no remembered position:

window.AisMapConfigOverrides = {
  getAccessToken: getToken,
  defaultCenter: [28.97, 41.01],
  defaultResolution: 300,
  rememberLastPosition: false,
  disableProjectionSelection: true
};

Coverage of one group only (the same 10000 ft title exists in several groups, so the path is used):

window.AisMapConfigOverrides = {
  getAccessToken: getToken,
  addDefaultLayers: [
    'Ibosoft ATC 1090 MHz Coverage/10000 ft',
    'Ibosoft ATC 1090 MHz Coverage/30000 ft'
  ]
};