Tento článek je zkráceným překladem článku Using WebAPIs to make the web layer more capable od  Roberta Nymana a je zde zveřejněn pod licencí CC-BY-SA 3.0.

Ve Firefox OS najdete tři typy WebAPI:

• Základní API
• Privilegovaná API
• Certified APIs

Kompletní přehled základních APIs

• Vibration API
• Screen Orientation
• Geolocation API
• Mouse Lock API
• Open WebApps
• Network Information API
• Battery Status API
• Alarm API
• Web Activities
• Push Notifications API
• WebFM API
• WebPayment
• IndexedDB
• Ambient light sensor
• Proximity sensor
• Notification
• FMRadio

Ukázky použití základních API

Battery Status API

Toto API detekuje úroveň nabití baterie zařízení, jakou dobu nabití baterie vydrží a zda je baterie právě nabíjena či nikoliv.

var battery = navigator.battery;

if (battery) {

    var batteryLevel = Math.round(battery.level * 100) + "%",

        charging = (battery.charging)? "" : "not ",

        chargingTime = parseInt(battery.chargingTime / 60, 10),

        dischargingTime = parseInt(battery.dischargingTime / 60, 10);

        // Nastavení událostí
        battery.addEventListener("levelchange", showStatus);
        battery.addEventListener("chargingchange", showStatus);
        battery.addEventListener("chargingtimechange", showStatus);
        battery.addEventListener("dischargingtimechange", showStatus);

}

Vibration API

Spustí vibraci zařízení, buď jednorázovou nebo dle zadaného vzoru.

// Vibruj jednu vteřinu
navigator.vibrate(1000);

// Vibrační vzor [vibrationTime, pause,…]

navigator.vibrate([200, 100, 200, 100]);

// Vibruj 5 vteřin
navigator.vibrate(5000);

// Zastav vibrace
navigator.vibrate(0);

Screen Orientation

Umožní vývojáři uzamknout orientaci obrazovky nebo specifikovat, jaká by měla být její primární orientace.

/*
    Možné hodnoty:
        "landscape", 
        "portrait"
        "landscape-primary"
        "landscape-secondary"
        "portrait-primary"
        "portrait-secondary"

*/
var portraitLock = screen.mozLockOrientation("portrait");
if (portraitLock) {
    console.log("Uzamkli jsme obrazovku ve svislé orientaci");
}

Geolocation API

Zjištění aktuální polohy uživatele – vyžaduje schválení uživatele.

navigator.geolocation.getCurrentPosition(function (position) {
    /* 
        Získá zeměpisnou šířku a délku:
            position.coords.latitude
            position.coords.longitude
    */
};

Mouse Lock API

Uzamčení ukazatele myši – vhodné, pokud nechcete, aby interakce s myší skončila, když ukazatel překročí hranice okna prohlížeče, ale pokračovala – např. při provádění rotace o 360 stupňů.

var docElm = document.documentElement;

// Vyžádej si uzamčení ukazatele myši
docElm.requestPointerLock = elem.requestPointerLock || 
                            elem.mozRequestPointerLock || 
                            elem.webkitRequestPointerLock;

docElm.requestPointerLock();

document.addEventListener("mousemove", function(e) {
    var movementX = e.movementX       ||
                    e.mozMovementX    ||
                    e.webkitMovementX ||
                    0,
        movementY = e.movementY       ||
                    e.mozMovementY    ||
                    e.webkitMovementY ||
                    0;

    // Získej delta hodnoty pohybu myši
    console.log("movementX=" + movementX, "movementY=" + movementY);  
}
);

Open WebApps

Jedná se o API, které obstarává instalaci Open Web aplikací.

var installApp = navigator.mozApps.install(manifestURL);

// Instalace proběhla úspěšně
installApp.onsuccess = function(data) {
    console.log("Success, app installed!");
};

// Instalace se nepovedla
installApp.onerror = function() {
    console.log("Install failed\n:" + installApp.error.name);
};

Network Information API

Získá informace o síťové konektivitě.

var connection = window.navigator.mozConnection,
    online = connection.bandwidth,
    metered = connection.metered;

/* online může vracet:
    0 = offline
    Infinity, když neznáme bandwidth
    Odhad MB/s
    metered = konektivita je měřena, tj. je nějakým způsobem od ISP limitována
*/

Alarm API

Umožní nastavit budík.

request = navigator.mozAlarms.add(
    new Date("May 15, 2012 16:20:00"), 
    "honorTimezone", 
    {
        mydata: "my event"
    }
);

Web Activities

Pomocí Web Activities můžete specifikovat tzv. intents, jaké aplikace podporuje a jaké akci má při nich vykonat. Více o Web Activities najdete v jiném článku.

var pick = new MozActivity({
     name: "pick",
     data: {
         type: ["image/png", "image/jpg", "image/jpeg"]
     
}
 });

pick.onsuccess = function () {

    var img = document.createElement("img");
    img.src = window.URL.createObjectURL(this.result.blob);
    document.body.appendChild(img);
};

Push Notifications API

Způsob, jakým může webová stránka posílat zprávy uživatelům, kteří aktuálně nesurfují na jejich webu. API je ve stádiu návrhu a zatím nebylo implementováno. Více najdete v dokumentaci k PushAPI.

function getPushURL() {
    var push = navigator.push ||
                navigator.mozPush ||
                navigator.webkitPush;

    // Získej svolení uživatele k odebírání notifikací
    var request = push.requestURL(watoken, PbK);

    request.onsuccess = function () {
        var url = request.result.url;
        console.log('Push URL: ' + url);
    };
}

WebFM API

Webová implementace FM rádia.

var fmRadio = navigator.fm || navigator.mozFMRadio || navigator.mozFM;
fmRadio.frequency = 106.7;

WebPayment

Používá se pro tzv. in-app platby prostřednictvím JSON Web Token (JWT).

var request = navigator.mozPay(JWTs);
request.onsuccess = function () {
    // Money!
};

IndexedDB

Strukturované úložiště na straně klienta nabízející výkonné vyhledávání. Více o něm najdete v článcích Using IndexedDB a Storing images and files in IndexedDB.

// Vytvoř/otevři databázi
var request = indexedDB.open("elephantFiles", 1),
     createObjectStore = function (dataBase) {
        console.log("Creating objectStore")
        dataBase.createObjectStore("elephants");
};

request.onsuccess = function (event) {
    console.log("Success creating/accessing IndexedDB database");
    db = request.result;

    db.onerror = function (event) {
        console.log("Error creating/accessing IndexedDB database");
    };
}

// Needed for creating database/upgrading to a new version
request.onupgradeneeded = function (event) {
    createObjectStore(event.target.result);
};

Ambient light sensor

Umožní detekovat úroveň osvětlení prostředí a dle toho nabídnout uživateli odlišné verze.

window.addEventListener("devicelight", function (event) {

    /* Hladina osvětlení v luxech

       Hodnota pro "dim" je obvykle pod 50 luxů,
       a pro "bright" nad 10000 luxů
    */
    console.log(event.value);

});

window.addEventListener("lightlevel", function (event) {
    // Possible values: "normal", "bright", "dim"
    console.log(event.value);

});

Proximity sensor

Zjistí, jak daleko je zařízení od jiného objektu.

window.addEventListener("deviceproximity", function (event) {

    // Zjistí vzdálenost zařízení, v cm
    console.log(event.value);


    // Maximální vzdálenost, kterou je senzor schopen určit, v cm
    console.log(event.max);


    // Minimální vzdálenost, kterou je senzor schopen určit, v cm
    console.log(event.min);
});

Notification

Umožní zobrazit uživateli upozornění (notifikace).

var notification = navigator.mozNotification;

notification.createNotification(
    "See this", 
    "This is a notification"
);
// Můžete přidat volitelný třetí parametr,,
// který bude obsahovat URL icony

Privilegovaná API

Tato API mohou být používána jen v privilegovaných aplikacích.

Kompletní přehled:

• Device Storage API
• Browser API
• TCP Socket API
• Contacts API
• systemXHR

Device Storage API

Zpřístupňuje soubory uložené v zařízení.

var storage = navigator.getDeviceStorage("videos"),

    cursor = storage.enumerate();


cursor.onerror = function() {
    console.error("Error in DeviceStorage.enumerate()", cursor.error.name);

};



cursor.onsuccess = function() {

    if (!cursor.result)
 
        return;

    }


    var file = cursor.result;

    // Pokud se jedná o video, přeskoč ho
    if (file.type.substring(0, 6) !== "video/") {

        cursor.continue();

        return;
    }

    // Pokud video nejde přehrát, přeskoč ho
    var testplayer = document.createElement("video");

    if (!testplayer.canPlayType(file.type)) {

        cursor.continue();

        return;
    }

    // Zobraz soubor
    console.log(file.name);
};

Browser API

Slouží k implementaci vašeho vlastního webového prohlížeče. Více najdete na stránce BrowserAPI.

iframe.addEventListener("mozbrowserlocationchange", function(e) {
    console.log(e.detail);
});

iframe.addEventListener("mozbrowsersecuritychange", function(e) {
    // "secure", "insecure", or "broken".  "broken" značí smíšený obsah.
    console.log(e.detail.state);
});

iframe.addEventListener("mozbrowsercontextmenu", function(e) {
    // Zobrazí kontextovou nabídku
});

TCP Socket API

Nízkoúrovňové API pro TCP socket, zahrnuje podporu SSL.

var TCPSocket = navigator.mozTCPSocket.open(
    host, 
    port, 
    {
        useSSL: crypto,
        binaryType: "arraybuffer"
    }
);

Contacts API

Zpřístupňuje kontakty uložené na zařízení – přidávání, čtení, editaci.

var contact = new mozContact();

contact.init({name: "Tom"});

var request = navigator.mozContacts.save(contact);

request.onsuccess = function() {
    console.log("Success");

};



request.onerror = function() {
    console.log("Error")

};

systemXHR

Umožňuje XMLHTTPRequest napříč jednotlivými doménami. V sekci permissions v manifestu specifikujte  – "systemXHR":{} – a můžete ho použít.

var xhr = new XMLHttpRequest();
xhr.open("GET", anyURL, true);

Certifikovaná API

Certifikovaná API jsou dostupná pouze systému a předinstalovaným aplikacím.

Kompletní přehled:

• WebTelephony
• WebSMS
• Idle API
• Settings API
• Power Management API
• Mobile Connection API
• WiFi Information API
• WebBluetooth
• Permissions API
• Network Stats API
• Camera API
• Time/Clock API
• Attention screen
• Voicemail

Platform support

Uvedená API jsou v různém stádiu realizace, více o tom najdete v přehledu plánovaných API pro Firefox OS.

Plánovaná API

Ačkoliv se na nich zatím nepracuje, zde je přehled API, která jsou plánována do budoucna.

• Resource lock API
• UDP Datagram Socket API
• Peer to Peer API
• WebNFC
• WebUSB
• HTTP-cache API
• Calendar API
• Spellcheck API
• LogAPI
• Keyboard/IME API
• WebRTC
• FileHandle API
• Sync API

Otestujte nová API

Některá z uvedených API si můžete vyzkoušet v Firefox OS Boilerplate App, dostupné z  webapp.js.