Vdelajte preverjanje značk na svojo spletno stran (brez iframa, brez SDK-ja)

Če izdajate poverilnice, vas bo prej ali slej nekdo vprašal: »Kako vem, da je ta značka resnična?« Iskren odgovor nikoli ne sme biti »zaupajte PNG-ju«. Open Badge v2.0 to rešuje z javno, strojno berljivo končno točko za preverjanje, vgradnja gradnika »Preverjeno« na vašo stran pa vzame približno deset vrstic kode – brez iframa, brez vdelane skripte tretje osebe in brez SDK-ja.

Ta objava prikaže, kako natančno poklicati končno točko in izrisati rezultat, v čistem JavaScriptu ter na strežniku v Node in Pythonu. Pojasni tudi, kaj preverjanje dejansko preverja, kam se končna točka umešča ob človeku namenjene strani, ki jih badges.ninja že ponuja prejemnikom, in napake, zaradi katerih gradnik za preverjanje videti dokončan, a na tihem ne dokazuje ničesar.

Kaj »preverjeno« v resnici pomeni

Trditev Open Badge v2.0 je dokument JSON-LD s stalno obliko: sama trditev (kdo jo je prejel, kdaj), sklic na BadgeClass (kaj je, kdo določa merila) in sklic na profil izdajatelja (kdo jamči zanjo). Ko značko »preverite«, dejansko preverjate tri ločene stvari:

1. Ali trditev obstaja in se razreši. ID nagrade je resničen, ni uganjen ali ponarejen.
2. Ali je bila preklicana. Izdajatelj lahko značko naknadno prekliče – poverilnica, izdana pomotoma, kršitev pravil, potekla certifikacija – in pravilen preverjevalnik mora to prikazati, ne le potrditi, da zapis obstaja.
3. Ali veriga drži skupaj. Sklici trditve na značko in izdajatelja se dejansko razrešijo na resnične, ujemajoče se zapise, ne na osirotele ali neskladne ID-je.

Gradnik, ki le pokliče URL in preveri status 200, popolnoma zgreši točko 2. Preklicana trditev se še vedno brez težav razreši – v vsebini le nosi zastavico preklica. Če vaš gradnik preverja samo, »ali je zahteva uspela«, bo preklicana poverilnica prikazana kot preverjena, kar je slabše, kot če gradnika sploh ne bi imeli.

Javna stran za ljudi proti končni točki API-ja

Vsaka nagrada, izdana na https://badges.ninja, dobi javni URL, ki ga prejemniki lahko neposredno delijo, za ogled pa registracija ni potrebna:

Na to stran bo večina prejemnikov povezala z LinkedIna, življenjepisa ali podpisa v e-pošti – ustvarjena je za ljudi, prikaže sliko značke, izdajatelja in datum izdaje, za delovanje pa od vas ne potrebuje ničesar. Spodnja končna točka API-ja vrne isto trditev kot strukturiran JSON-LD, kar potrebujete, ko gradite lasten uporabniški vmesnik, namesto da bi samo povezali na naš.

Končna točka

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

Glava za overjanje ni potrebna – končna točka je namenoma javna, saj je bistvo Open Badges prav v tem, da lahko kdor koli (delodajalec, kadrovik, strokovna zbornica) preveri poverilnico brez računa. Podrobnosti pogodbe, vključno z natančnimi imeni polj v vrnjeni trditvi, so v dokumentaciji za preverjanje.

Podajte GUID nagrade, ki ga imate bodisi iz svojih zapisov o izdaji bodisi ga razberete iz povezave badges.ninja/awards/<guid>, ki ste jo prejeli od prejemnika.

Čisti JS: fetch in izris

To je celoten gradnik. Brez koraka gradnje, brez paketa npm, preprosto ga vstavite na katero koli stran:

<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>

Zamenjajte REPLACE_WITH_AWARD_ID z resničnim GUID-om nagrade. To je celotna integracija na strani odjemalca: ni meje iframa, s katero bi se bojevali s CSS-jem, in ni skripte tretje osebe, ki bi ob preverjanju vlekla s seboj lastno analitiko ali sledilne piksle.

Na strežniku: Node

Če raje preverjate v zaledju – denimo preden na profilni strani pod vašim nadzorom prikažete značko »Preverjeni partner« ali preden v postopku uvajanja sprejmete poverilnico kot dokaz – je fetch enak, brez dela z DOM-om:

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 strežniku: 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 primera odgovor, ki ni 200, obravnavata kot »ni najdeno«, namesto da bi vrgla izjemo. Pokvarjen ali uganjen ID nagrade je za javno končno točko za preverjanje pričakovan vnos, ne izjemen, zato ga obravnavajte kot običajno vejo, ne kot ujeto napako.

Oblikovanje rezultata namesto vdelave tujega uporabniškega vmesnika

Ker je gradnik zgoraj le klic fetch v vaš lasten DOM, je vsak piksel vaš. Pogost vzorec so tri vizualna stanja, preslikana neposredno iz odgovora:

• Preverjeno – zelena kljukica, »Preverjeno« in datum izdaje, oblikovano v slogu komponent značk/oznak na vaši strani.
• Preklicano – zadušeno ali rdeče stanje, ki prikaže razlog preklica, namesto da bi ga skrilo. Prejemniki in tretje osebe imajo korist od iskrenega »zakaj«, ne tihe napake.
• Ni najdeno – vizualno ga obravnavajte enako kot »preklicano« (ne izrisujte lažnega uspešnega stanja), a z drugačnim besedilom, saj sta napačen ID in namerni preklic za bralca strani različni situaciji.

Nič od tega ne zahteva knjižnice komponent. switch na verified / revoked / not_found in trije razredi CSS to pokrijejo.

Predpomnjenje, da končne točke ne zasujete

Končna točka za preverjanje je javna in brez overjanja, kar pomeni tudi, da vam ni treba skrbeti za stroške kreditov na zahtevo – a če jo na strani odjemalca kličete brez predpomnjenja, je to še vedno omrežni krog ob vsakem nalaganju strani. Za stran, ki vsakemu obiskovalcu prikaže isto značko (na primer značka »Preverjeni partner« v nogi), rezultat predpomnite na strežniku s kratkim TTL-jem – pet do petnajst minut povsem zadostuje, saj preklici niso hitro spreminjajoč se signal – namesto da ga ob vsaki zahtevi znova pridobivate:

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;
}

Za gradnik na obiskovalca (prejemnik, ki na osebno stran vdela svojo poverilnico) predpomnjenje preskočite in ga ob nalaganju strani preprosto pokličite sveže – dodatna zahteva je pri takem obsegu zanemarljiva.

Kaj badges.ninja prejemnikom že ponuja

Preden zgradite popolnoma prilagojeno vdelavo, je dobro vedeti, kaj je na voljo že takoj. Javna stran vsake nagrade vsebuje pripravljene izrezke za deljenje in vdelavo, ki jih prejemniki kopirajo neposredno, brez kode na njihovi strani:

Če je vaš primer uporabe »naj prejemnik pokaže, da je njegova značka resnična«, je povezava na njegovo stran badges.ninja/awards/<guid> pogosto preprostejša od gradnje lastnega gradnika – to je človeška stran, prikazana prej, in že sama loči med preverjenim in preklicanim. Gradnik iz te objave zgradite, kadar morate stanje preverjanja prikazati znotraj uporabniškega vmesnika svojega izdelka – imenika partnerjev, notranje nadzorne plošče za revizije, kadrovskega orodja, ki preverja kandidatove navedene certifikate – kjer povezava na drugo spletno mesto ni prava uporabniška izkušnja.

Zakaj ne iframe ali gradnik ponudnika?

Nekatere platforme vam ponudijo izrezek, kot je <iframe src="https://vendor.example.com/verify-widget">, za vdelavo stanja preverjanja. Deluje, a ima resne stroške: vsebine ne morete preoblikovati po svoji strani (obtičite pri CSS-ju, ki ga je dostavil ponudnik), uvaja medizvorni dokument, ki ga mora vaša Content-Security-Policy izrecno dovoliti, in vsako nalaganje strani sproži zahtevo na gostitelja iframa tretje osebe, ne glede na to, ali obiskovalca stanje preverjanja sploh zanima. Gradnik z dvema klicema fetch se vsemu temu izogne – to je vaš DOM, vaše oblikovanje, in se zažene le, ko se odločite za klic.

Prehod celotne verige preverjanja

Če gradite kaj temeljitejšega od gradnika stanja – orodje za revizijo, ki preverja serijo poverilnic, ali poročilo o skladnosti – prehodite celotno verigo, namesto da se ustavite pri trditvi. Trditev se sklicuje na URL badge (BadgeClass: ime, opis, merila), BadgeClass pa se sklicuje na URL issuer (profil organizacije). Strog preverjevalnik razreši vse tri in potrdi, da so notranje skladni – značka res pripada izdajatelju, ki ga navaja, trditev res napotuje na značko, ki jo navaja – ne le da trditev na vrhu vrne 200. To je več globine, kot jo potrebuje gradnik stanja za posamezno poverilnico, a je dobro vedeti, da taka oblika obstaja, če vas partner ali revizor kdaj vpraša: »Kako globoko seže vaše preverjanje?«

Pogoste napake, ki se jim izognite

• Preverjanje samo HTTP statusa. Kot rečeno zgoraj, se preklicana trditev še vedno razreši. Vedno preberite assertion.revoked, preverjenosti ne sklepajte samo iz statusne kode.
• Trdo kodiran ID nagrade v skupni komponenti. Če je gradnik namenjen ponovni uporabi na straneh številnih prejemnikov, ID nagrade sprejmite kot parameter (atribut data, poizvedbeni niz, prop), ne kot konstanto, vpeto v skripto.
• Tiho požiranje omrežnih napak. Blok try/catch, ki ničesar ne zabeleži in pokaže isto besedilo »ni najdeno« kot za resnično manjkajočo značko, kasneje oteži razhroščevanje. V vejah napak – vsaj v dnevnikih – ločite »omrežni klic ni uspel« od »API je rekel ne«.
• Ponovno preverjanje ob vsakem izrisu v odjemalski aplikaciji. Če gradnik živi znotraj komponente React ali Vue, ki se pogosto znova izrisuje, preverite enkrat na vpetje (ali enkrat na okno predpomnjenega TTL-ja, kot v razdelku o predpomnjenju), ne ob vsakem ponovnem izrisu.

Ali to stane kredite in ali deluje v brezplačnem paketu?

Ne. Končna točka za preverjanje je namenoma zunaj sistema kreditov, ki ureja izdajanje – preverjanje veljavnosti značke izdajatelja nič ne stane, klicatelj pa ne potrebuje računa, ključa API ali kakršne koli ravni paketa. To velja ne glede na to, ali je bila značka izdana v paketu Free, Starter ali Pro: preverjanje je lastnost same poverilnice, ne funkcija, vezana na izdajateljevo naročnino. Zato lahko gradnik varno postavite na javno stran z nepredvidljivim prometom (stran s kariero, imenik partnerjev), ne da bi vas skrbele omejitve hitrosti, vezane na vaš račun – kličete javno končno točko samo za branje, ne overjene poti API-ja.

Nekaj velja izrecno poudariti: trditev JSON, ki jo vrne končna točka, ne vsebuje prejemnikovega surovega e-poštnega naslova. E-pošta prejemnika je v zaledju shranjena zgoščena, prav zato, da iz javnega odgovora za preverjanje ni mogoče izluščiti osebnih kontaktnih podatkov – dobite dovolj za potrditev poverilnice (značka, izdajatelj, datumi, stanje preklica), ne da bi končno točko spremenili v orodje za zbiranje potencialnih strank za vsakogar, ki prebira ID-je nagrad.

Ste pripravljeni izdati svojo prvo preverljivo poverilnico?

Začnite brezplačno v badges.ninja – vizualni oblikovalnik, javna stran za preverjanje, PDF-certifikat, izhod Open Badge v2.0. Kreditna kartica ni potrebna.

Za celotno komentirano strukturo vseh polj v trditvi si oglejte referenco polj JSON-LD. In če poverilnice izdajate programsko, ne le preverjate, hitri začetek z API-jem pokriva overjanje in klic za ustvarjanje nagrade, iz katerega izhaja izhod te končne točke.