Vložte overenie odznakov na svoj web (bez iframe, bez SDK)

Ak vydávate osvedčenia, skôr či neskôr sa niekto opýta: „ako viem, že je tento odznak pravý?“ Úprimná odpoveď nikdy nesmie znieť „dôverujte PNG“. Open Badge v2.0 to rieši verejným strojovo čitateľným endpointom na overenie a umiestnenie widgetu „Overené“ na váš web zaberie asi desať riadkov kódu — nie iframe, nie skript tretej strany a nie SDK.

Tento článok presne ukazuje, ako endpoint zavolať a vykresliť výsledok, vo vanilla JavaScripte a na serveri v Node a Pythone. Pokrýva aj to, čo „overenie“ v skutočnosti kontroluje, kde endpoint zapadá vedľa stránok pre ľudí, ktoré badges.ninja už ponúka príjemcom, a chyby, vďaka ktorým widget na overenie vyzerá hotovo, no potichu nedokazuje nič.

Čo „overené“ v skutočnosti znamená

Assertion Open Badge v2.0 je JSON-LD dokument s pevnou štruktúrou: samotný assertion (kto ho dostal a kedy), odkaz na BadgeClass (čo to je a kto určuje kritériá) a odkaz na profil vydavateľa (kto za ním stojí). Keď odznak „overujete“, v skutočnosti kontrolujete tri samostatné veci:

1. Existuje assertion a dá sa vyriešiť. ID ocenenia je skutočné, nie uhádnuté ani pozmenené.
2. Bol odvolaný. Vydavateľ môže odznak dodatočne odvolať — osvedčenie vydané omylom, porušenie pravidiel, vypršaná certifikácia — a správny overovateľ to musí zobraziť, nielen potvrdiť, že záznam existuje.
3. Drží reťaz pokope. Odkazy assertionu na odznak a vydavateľa sa skutočne vyriešia na reálne, zodpovedajúce záznamy, nie na osirelé či nezhodné ID.

Widget, ktorý len pingne URL a skontroluje stavový kód 200, úplne míňa bod 2. Odvolaný assertion sa stále normálne vyrieši — len v dátach nesie príznak odvolania. Ak váš widget kontroluje iba „uspela požiadavka“, odvolané osvedčenie sa zobrazí ako overené, čo je horšie, než nemať widget vôbec.

Verejná stránka pre ľudí vs. API endpoint

Každé ocenenie vydané na https://badges.ninja dostane verejnú URL, ktorú môžu príjemcovia priamo zdieľať, bez registrácie na jej zobrazenie:

Na túto stránku bude väčšina príjemcov odkazovať z LinkedInu, zo životopisu alebo z podpisu e-mailu — je vytvorená pre ľudí, zobrazuje obrázok odznaku, vydavateľa a dátum vydania a nevyžaduje od vás nič, aby fungovala. Endpoint nižšie vracia ten istý assertion ako štruktúrovaný JSON-LD, čo potrebujete, keď budujete vlastné rozhranie namiesto toho, aby ste len odkazovali na naše.

Endpoint

GET https://api.badges.ninja/certify-badge/award/{guid}

Nie je potrebná žiadna hlavička auth — je to zámerne verejné, pretože celý zmysel Open Badges je, aby ktokoľvek (zamestnávateľ, recruiter, licenčný orgán) mohol overiť osvedčenie bez účtu. Úplné podrobnosti zmluvy vrátane presných názvov polí vo vrátenom assertione sú v dokumentácii k overeniu.

Odovzdajte GUID ocenenia, ktoré budete mať buď z vlastných záznamov o vydávaní, alebo vyčítané z odkazu badges.ninja/awards/<guid>, ktorý s vami zdieľal príjemca.

Vanilla JS: fetch a vykreslenie

Toto je celý widget. Bez build kroku, bez npm balíka, jednoducho ho vložte na ľubovoľnú stránku:

<div id="badge-verify"></div>
<script>
  async function renderBadgeVerification(awardId, mountId) {
    const el = document.getElementById(mountId);
    el.textContent = "Checking badge status";
    try {
      const res = await fetch(
        `https://api.badges.ninja/certify-badge/award/${awardId}`
      );
      if (!res.ok) {
        el.textContent = "Credential not found.";
        return;
      }
      const assertion = await res.json();
      // —— revocation check first, a resolvable assertion isn't enough on its own
      if (assertion.revoked) {
        el.textContent = `Revoked: ${assertion.revocationReason || "no reason given"}`;
        return;
      }
      el.textContent = `Verified, issued ${new Date(assertion.issuedOn).toLocaleDateString()}`;
    } catch (err) {
      el.textContent = "Verification check failed.";
    }
  }
  renderBadgeVerification("REPLACE_WITH_AWARD_ID", "badge-verify");
</script>

Nahraďte REPLACE_WITH_AWARD_ID skutočným GUID ocenenia. To je celá integrácia na strane klienta: žiadna hranica iframe, s ktorou by ste museli zápasiť v CSS, a žiadny skript tretej strany, ktorý by popri overení ťahal vlastnú analytiku či sledovacie pixely.

Na strane servera: Node

Ak radšej overujete na backende — povedzme pred zobrazením odznaku „Overený partner“ na profilovej stránke, ktorú ovládate, alebo pred prijatím osvedčenia ako dôkazu v onboardingu — fetch je rovnaký, len bez časti s DOM:

async function verifyAward(awardId) {
  const res = await fetch(
    `https://api.badges.ninja/certify-badge/award/${awardId}`
  );
  if (!res.ok) return { verified: false, reason: "not_found" };
  const assertion = await res.json();
  if (assertion.revoked) {
    return { verified: false, reason: assertion.revocationReason || "revoked" };
  }
  return { verified: true, issuedOn: assertion.issuedOn, badge: assertion.badge };
}

Na strane servera: Python

import requests
# —— resolve the assertion, then check revocation before trusting it
def verify_award(award_id):
    res = requests.get(f"https://api.badges.ninja/certify-badge/award/{award_id}")
    if res.status_code != 200:
        return {"verified": False, "reason": "not_found"}
    assertion = res.json()
    if assertion.get("revoked"):
        return {"verified": False, "reason": assertion.get("revocationReason", "revoked")}
    return {"verified": True, "issued_on": assertion.get("issuedOn"), "badge": assertion.get("badge")}

Oba príklady považujú odpoveď iného kódu ako 200 za „nenájdené“ namiesto vyhodenia chyby. Pokazené alebo uhádnuté ID ocenenia je pre verejný endpoint na overenie očakávaný vstup, nie výnimka, preto ho spracujte ako bežnú vetvu, nie ako zachytenú chybu.

Štýlovanie výsledku namiesto vkladania cudzieho rozhrania

Keďže widget vyššie je len volanie fetch do vášho vlastného DOM, každý pixel máte vo vlastných rukách. Bežný vzor sú tri vizuálne stavy odvodené priamo z odpovede:

• Overené — zelená fajka s textom „Overené“ a dátumom vydania, štýlovaná tak, aby ladila s komponentmi odznakov/štítkov na vašom webe.
• Odvolané — tlmený alebo červený stav, ktorý zobrazí dôvod odvolania namiesto toho, aby ho skryl. Príjemcovia aj tretie strany profitujú z úprimného „prečo“, nie z tichého zlyhania.
• Nenájdené — vizuálne ho berte rovnako ako „odvolané“ (nezobrazujte falošný stav úspechu), ale s iným textom, pretože zlé ID a zámerné odvolanie sú pre čitateľa stránky odlišné situácie.

Nič z toho nevyžaduje knižnicu komponentov. Stačí jeden switch nad verified / revoked / not_found a tri CSS triedy.

Cache, aby ste endpoint nezaťažovali

Endpoint na overenie je verejný a bez autentifikácie, čo znamená aj to, že neexistuje cena v kreditoch za požiadavku — no ak ho voláte z klienta bez cache, stále ide o sieťový round trip pri každom načítaní stránky. Pri stránke, ktorá každému návštevníkovi zobrazuje ten istý odznak (napríklad odznak „Overený partner“ v pätičke), uložte výsledok do cache na serveri s krátkym TTL — päť až pätnásť minút úplne stačí, keďže odvolania nie sú rýchlo sa meniaci signál — namiesto opätovného načítavania pri každej požiadavke:

const cache = new Map();
async function verifyAwardCached(awardId, ttlMs = 10 * 60 * 1000) {
  const hit = cache.get(awardId);
  if (hit && Date.now() - hit.at < ttlMs) return hit.result;
  const result = await verifyAward(awardId);
  cache.set(awardId, { result, at: Date.now() });
  return result;
}

Pri widgete pre jedného návštevníka (príjemca vkladá vlastné osvedčenie na osobný web) cache vynechajte a pri načítaní stránky ho jednoducho zavolajte nanovo — extra požiadavka je v takom meradle zanedbateľná.

Čo badges.ninja príjemcom už ponúka

Skôr než vytvoríte plne vlastné vloženie, oplatí sa vedieť, čo je už k dispozícii hneď po inštalácii. Verejná stránka každého ocenenia obsahuje hotové úryvky na zdieľanie a vloženie, ktoré môžu príjemcovia priamo skopírovať, bez akéhokoľvek kódu na ich strane:

Ak je váš prípad použitia „nech príjemca ukáže, že jeho odznak je pravý“, odkaz na jeho stránku badges.ninja/awards/<guid> je často jednoduchší než vytváranie vlastného widgetu — je to stránka pre ľudí zobrazená vyššie a rozdiel medzi overeným a odvolaným už rieši za vás. Vlastný widget z tohto článku vytvorte vtedy, keď potrebujete stav overenia vykresliť vo vnútri rozhrania vášho produktu — adresár partnerov, interný auditný dashboard, nástroj na nábor kontrolujúci uvádzané certifikácie kandidáta — kde odkaz na iný web nie je správny UX.

Prečo nie iframe alebo widget od dodávateľa?

Niektoré platformy vám dajú úryvok ako <iframe src="https://vendor.example.com/verify-widget"> na vloženie stavu overenia. Funguje to, no so skutočnými nevýhodami: obsah nemôžete prispôsobiť svojmu webu (ste odkázaní na CSS, ktoré dodávateľ dodal), zavádza sa cross-origin dokument, ktorý musí vaša Content-Security-Policy výslovne povoliť, a pri každom načítaní stránky ide požiadavka na hostiteľa iframe tretej strany bez ohľadu na to, či návštevníka stav overenia vôbec zaujíma. Widget s dvoma volaniami fetch sa vyhne všetkým trom — je to váš DOM, váš štýl a spustí sa, len keď sa rozhodnete ho zavolať.

Prechod celým reťazcom overenia

Ak budujete niečo dôkladnejšie než stavový widget — napríklad auditný nástroj, ktorý kontroluje dávku osvedčení, alebo správu o súlade — prejdite celý reťazec namiesto zastavenia pri assertione. Assertion odkazuje na URL badge (BadgeClass: názov, popis, kritériá) a BadgeClass zase odkazuje na URL issuer (profil organizácie). Dôsledný overovateľ vyrieši všetky tri a potvrdí, že sú vnútorne konzistentné — odznak skutočne patrí vydavateľovi, ktorého uvádza, assertion skutočne odkazuje na odznak, ktorý uvádza — nielen že assertion najvyššej úrovne vráti 200. Je to viac hĺbky, než widget pre jedno osvedčenie potrebuje, no je dobré vedieť, že taký tvar existuje, ak sa partner alebo audítor niekedy opýta: „ako hlboko vaše overenie v skutočnosti siaha?“

Časté chyby, ktorým sa vyhnúť

• Kontrola iba HTTP stavu. Ako sme uviedli vyššie, odvolaný assertion sa stále vyrieši. Vždy čítajte assertion.revoked, overenie nevyvodzujte iba zo stavového kódu.
• Pevne zadané ID ocenenia v zdieľanom komponente. Ak má byť widget opakovane použiteľný na stránkach mnohých príjemcov, ID ocenenia preberajte ako parameter (data atribút, query string, prop), nie ako literál zapísaný v skripte.
• Tiché prehĺtanie sieťových chýb. try/catch, ktorý nič nezaloguje a zobrazí rovnaký text „nenájdené“ ako pri skutočne chýbajúcom odznaku, neskôr komplikuje ladenie. Rozlišujte „sieťové volanie zlyhalo“ od „API povedalo nie“ vo vetvách chýb, aspoň v logoch.
• Opakované overovanie pri každom vykreslení v klientskej aplikácii. Ak widget žije vo vnútri komponentu React alebo Vue, ktorý sa často prekresľuje, overujte raz pri pripojení (alebo raz za okno cachovaného TTL podľa sekcie o cache vyššie), nie pri každom prekreslení.

Stojí to kredity a funguje to na bezplatnom pláne?

Nie. Endpoint na overenie je zámerne mimo systému kreditov, ktorý riadi vydávanie — kontrola, či je odznak platný, vydavateľa nič nestojí a nevyžaduje, aby volajúci návštevník mal účet, API kľúč alebo akúkoľvek úroveň plánu. Platí to bez ohľadu na to, či bol odznak vydaný na pláne Free, Starter alebo Pro: overenie je vlastnosťou samotného osvedčenia, nie funkciou viazanou na predplatné vydavateľa. Preto môžete tento widget bezpečne umiestniť na verejnú stránku s nepredvídateľnou návštevnosťou (stránka kariéry, adresár partnerov) bez obáv z limitov rýchlosti viazaných na váš účet — voláte verejný endpoint len na čítanie, nie autentifikovanú API trasu.

Jedna vec stojí za výslovné spomenutie: JSON assertionu vrátený endpointom neobsahuje surovú e-mailovú adresu príjemcu. E-mail príjemcu sa na backende ukladá zahashovaný práve preto, aby sa z verejnej odpovede na overenie nedali zbierať osobné kontaktné údaje — dostanete dosť na potvrdenie osvedčenia (odznak, vydavateľ, dátumy, stav odvolania), bez toho, aby sa z endpointu stal nástroj na získavanie leadov pre každého, kto prechádza ID ocenení.

Ste pripravení vydať svoje prvé overiteľné osvedčenie?

Začnite zadarmo na badges.ninja — vizuálny dizajnér, verejná stránka na overenie, PDF certifikát, výstup Open Badge v2.0. Kreditná karta nie je potrebná.

Úplnú anotovanú štruktúru každého poľa v assertione nájdete v referencii polí JSON-LD. A ak osvedčenia vydávate programovo, nielen ich overujete, API quickstart pokrýva autentifikáciu a volanie na vytvorenie ocenenia, z ktorého pochádza výstup tohto endpointu.