Lisa märgi kinnitamine oma veebilehele (ilma iframe'ita, ilma SDK-ta)

Kui sa väljastad tunnistusi, küsib keegi varem või hiljem: „Kuidas ma tean, et see märk on päris?” Aus vastus ei tohi kunagi olla „usalda PNG-d”. Open Badge v2.0 lahendab selle avaliku, masinloetava kinnitamise lõpp-punktiga ning „Kinnitatud” vidina lisamine oma lehele võtab umbes kümme rida koodi – ilma iframe’ita, ilma kolmanda osapoole manusskriptita ja ilma SDK-ta.

See postitus näitab täpselt, kuidas lõpp-punkti kutsuda ja tulemust kuvada: puhtas JavaScriptis ning serveris Node’is ja Pythonis. Samuti selgitab see, mida „kinnitamine” tegelikult kontrollib, kuidas lõpp-punkt sobitub inimestele mõeldud lehtedega, mida badges.ninja saajatele juba pakub, ning vigadega, mis panevad kinnitusvidina näima valmis, kuigi see vaikselt mitte midagi ei tõesta.

Mida „kinnitatud” tegelikult tähendab

Open Badge v2.0 väide on kindla kujuga JSON-LD dokument: väide ise (kes selle sai, millal), viide BadgeClass’ile (mis see on, kes kriteeriumid määrab) ja viide väljaandja profiilile (kes selle eest kostab). Kui sa märki „kinnitad”, kontrollid tegelikult kolme eraldi asja:

1. Kas väide on olemas ja lahendub. Auhinna ID on päris, mitte ära arvatud ega muudetud.
2. Kas see on tühistatud. Väljaandja võib märgi hiljem tühistada – eksikombel välja antud tunnistus, reeglite rikkumine, aegunud sertifikaat – ja korrektne kinnitaja peab seda näitama, mitte ainult kinnitama, et kirje on olemas.
3. Kas ahel peab koos. Väite viited märgile ja väljaandjale lahenduvad tegelikult päris ja omavahel sobivateks kirjeteks, mitte orbudeks jäänud või sobimatuteks ID-deks.

Vidin, mis ainult pingib URL-i ja kontrollib olekut 200, jätab punkti 2 täiesti märkamata. Tühistatud väide lahendub endiselt probleemideta – see lihtsalt kannab sisus tühistamise lippu. Kui sinu vidin kontrollib ainult seda, „kas päring õnnestus”, kuvatakse tühistatud tunnistus kinnitatuna, mis on hullem kui vidina täielik puudumine.

Avalik inimlehekülg vs. API lõpp-punkt

Iga https://badges.ninja keskkonnas välja antud auhind saab avaliku URL-i, mida saajad saavad otse jagada ja mille vaatamiseks pole registreerumist vaja:

Just sellele lehele lingib enamik saajaid LinkedInist, CV-st või e-kirja allkirjast – see on tehtud inimestele, näitab märgi pilti, väljaandjat ja väljaandmise kuupäeva ning ei vaja sinult toimimiseks midagi. Allolev API lõpp-punkt tagastab sama aluseks oleva väite struktureeritud JSON-LD-na, mida sa vajad siis, kui ehitad oma kasutajaliidest, selle asemel et lihtsalt meie lehele viidata.

Lõpp-punkt

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

Autentimispäist pole vaja – see on tahtlikult avalik, sest Open Badge’ide kogu mõte on, et igaüks (tööandja, värbaja, litsentsiamet) saab tunnistust kinnitada ilma kontota. Täielikud lepingu üksikasjad, sealhulgas tagastatud väite täpsed väljanimed, on kinnitamise dokumentatsioonis.

Edasta auhinna GUID, mis sul on kas oma väljastuskirjetest või mille sa võtad välja saaja jagatud lingist badges.ninja/awards/<guid>.

Puhas JS: fetch ja kuvamine

See on kogu vidin. Ilma ehitusetapita, ilma npm-paketita, pane see otse mis tahes lehele:

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

Asenda REPLACE_WITH_AWARD_ID päris auhinna GUID-iga. See ongi kogu kliendipoolne integratsioon: puudub iframe’i piir, millega CSS-iga heitlema peaks, ning puudub kolmanda osapoole skript, mis kinnituskontrolli kõrvale oma analüütika või jälgimispiksleid kaasa toob.

Serveripoolne: Node

Kui eelistad kinnitada taustasüsteemis – näiteks enne, kui kuvad enda hallataval profiililehel märki „Kinnitatud partner”, või enne, kui võtad tunnistuse sisseelamisvoos tõendina vastu –, on fetch sama, miinus DOM-i osa:

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

Serveripoolne: 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")}

Mõlemad näited käsitlevad vastust, mis pole 200, kui „ei leitud”, mitte erandina. Katkine või ära arvatud auhinna ID on avaliku kinnitamise lõpp-punkti puhul oodatav sisend, mitte erakordne, nii et käsitle seda tavalise harutena, mitte püütud veana.

Tulemuse kujundamine võõra kasutajaliidese manustamise asemel

Kuna ülaltoodud vidin on lihtsalt fetch-kutse sinu enda DOM-i, kuulub iga piksel sulle. Levinud muster on kolm visuaalset olekut, mis tuletatakse otse vastusest:

• Kinnitatud – roheline linnuke pluss „Kinnitatud” ja väljaandmise kuupäev, kujundatud sinu lehe märgi/sildi komponentide stiilis.
• Tühistatud – summutatud või punane olek, mis näitab tühistamise põhjust, mitte ei peida seda. Nii saajad kui kolmandad osapooled saavad kasu ausast „miks’ist”, mitte vaiksest tõrkest.
• Ei leitud – kuva seda visuaalselt samamoodi nagu „tühistatud” (ära kuva võlts-edu olekut), aga teistsuguse tekstiga, sest vale ID ja tahtlik tühistamine on lehe lugejale erinevad olukorrad.

Midagi sellest ei nõua komponendiraamatukogu. switch väärtuste verified / revoked / not_found peal ja kolm CSS-klassi katavad selle ära.

Vahemällu salvestamine, et sa lõpp-punkti ei räsiks

Kinnitamise lõpp-punkt on avalik ja autentimata, mis tähendab ka seda, et päringupõhise krediidikulu pärast pole vaja muretseda – kuid kui kutsud seda kliendipoolselt ilma vahemäluta, on see siiski võrgu edasi-tagasi tiir iga lehelaadimise peale. Lehe puhul, mis kuvab igale külastajale sama märki (näiteks jaluse märk „Kinnitatud partner”), salvesta tulemus serveris lühikese TTL-iga vahemällu – viis kuni viisteist minutit on täiesti piisav, sest tühistamised pole kiiresti muutuv signaal – selle asemel et iga päringu peal uuesti tuua:

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

Külastajapõhise vidina puhul (saaja manustab oma tunnistuse isiklikule lehele) jäta vahemälu vahele ja kutsu seda lehe laadimisel lihtsalt värskelt – lisapäring on sellise mahu juures tühine.

Mida badges.ninja saajatele juba pakub

Enne kui ehitad täiesti kohandatud manuse, tasub teada, mis on juba karbist väljas olemas. Iga auhinna avalik leht sisaldab valmis jagamis- ja manustamislõike, mida saajad saavad otse kopeerida, ilma et nad peaksid koodi kirjutama:

Kui sinu kasutusjuht on „lase saajal näidata, et tema märk on päris”, on lingi andmine tema lehele badges.ninja/awards/<guid> sageli lihtsam kui kohandatud vidina ehitamine – see on varem näidatud inimleht ja see teeb kinnitatud/tühistatud vahetegemise sinu eest ära. Ehita selle postituse kohandatud vidin siis, kui pead kinnitamise olekut kuvama oma toote kasutajaliideses – partnerikataloogis, sisemises auditipaneelis, värbamistööriistas, mis kontrollib kandidaadi väidetavaid sertifikaate –, kus teisele saidile viitamine pole õige kasutuskogemus.

Miks mitte iframe või tarnija vidin?

Mõned platvormid annavad sulle lõigu nagu <iframe src="https://vendor.example.com/verify-widget"> kinnitamise oleku manustamiseks. See töötab, aga sellel on tegelikud kulud: sisu ei saa oma lehega sobitada (oled kinni selles CSS-is, mille tarnija kaasa pani), see toob sisse ristpäritolu dokumendi, mille sinu Content-Security-Policy peab selgesõnaliselt lubama, ning iga lehelaadimine teeb päringu kolmanda osapoole iframe’i hostile sõltumata sellest, kas külastajat kinnitamise olek üldse huvitab. Kahe fetch-kutsega vidin väldib kõiki kolme – see on sinu DOM, sinu kujundus ja see jookseb ainult siis, kui sina otsustad seda kutsuda.

Kogu kinnitusahela läbikäimine

Kui ehitad midagi põhjalikumat kui olekuvidin – näiteks auditi tööriista, mis kontrollib tunnistuste hulka, või vastavusaruande –, käi läbi kogu ahel, mitte ära peatu väite juures. Väide viitab badge URL-ile (BadgeClass: nimi, kirjeldus, kriteeriumid) ja BadgeClass omakorda issuer URL-ile (organisatsiooni profiil). Range kinnitaja lahendab kõik kolm ja kinnitab, et need on sisemiselt kooskõlas – märk kuulub tõesti väljaandjale, kellele see viitab, väide viitab tõesti märgile, millele see väidab viitavat –, mitte ainult et ülemise taseme väide tagastab 200. See on rohkem sügavust, kui ühe tunnistuse olekuvidin vajab, aga väärt teadmist, et selline kuju on olemas, kui partner või audiitor kunagi küsib: „kui sügavale teie kinnitamine tegelikult ulatub?”

Levinud vead, mida vältida

• Ainult HTTP oleku kontrollimine. Nagu eespool kirjeldatud, lahendub tühistatud väide endiselt. Loe alati assertion.revoked, ära tuleta kinnitust ainult olekukoodist.
• Auhinna ID kõvakodeerimine jagatud komponenti. Kui vidin on mõeldud taaskasutamiseks paljude saajate lehtedel, võta auhinna ID parameetrina (data-atribuut, päringustring, prop), mitte skripti sisse põletatud literaalina.
• Võrgutõrgete vaikne alla neelamine. try/catch, mis midagi ei logi ja näitab sama teksti „ei leitud” nagu tõesti puuduva märgi puhul, teeb hilisema silumise valusaks. Eralda oma veaharudes – vähemalt logides – „võrgukutse ebaõnnestus” ja „API ütles ei”.
• Uuestikinnitamine iga renderduse peal kliendirakenduses. Kui vidin elab React’i või Vue komponendis, mis renderdub sageli uuesti, kinnita üks kord ühenduse kohta (või üks kord vahemälu TTL-akna kohta, vastavalt vahemälu jaotisele), mitte iga uuesti renderdamise peal.

Kas see maksab krediite ja kas see töötab tasuta plaanis?

Ei. Kinnitamise lõpp-punkt on tahtlikult väljaandmist reguleerivast krediidisüsteemist väljas – märgi kehtivuse kontrollimine ei maksa väljaandjale midagi ning seda kutsuval külastajal pole vaja kontot, API võtit ega ühtegi plaanitaset. See kehtib sõltumata sellest, kas märk anti välja Free, Starter või Pro plaanis: kinnitamine on tunnistuse enda omadus, mitte väljaandja tellimusega piiratud funktsioon. Seetõttu võid vidina julgelt panna avalikule lehele ettearvamatu liiklusega (karjäärileht, partnerikataloog), muretsemata sinu kontoga seotud päringupiirangute pärast – sa kutsud kirjutuskaitstud avalikku lõpp-punkti, mitte autenditud API teed.

Üht on väärt selgesõnaliselt öelda: lõpp-punkti tagastatud väite JSON ei sisalda saaja toorest e-posti aadressi. Saaja e-post hoitakse taustasüsteemis räsituna just selleks, et avalikust kinnitusvastusest ei saaks isiklikke kontaktandmeid kraapida – saad piisavalt tunnistuse kinnitamiseks (märk, väljaandja, kuupäevad, tühistamise olek), ilma et lõpp-punkt muutuks müügivihjete tööriistaks igaühele, kes auhinna ID-sid läbi käib.

Valmis väljastama oma esimest kontrollitavat tunnistust?

Alusta tasuta badges.ninjas – visuaalne kujundaja, avalik kinnitusleht, PDF-sertifikaat, Open Badge v2.0 väljund. Krediitkaarti pole vaja.

Iga väite välja täieliku annoteeritud struktuuri leiad JSON-LD väljade viitest. Ja kui sa väljastad tunnistusi programmiliselt, mitte ei kinnita neid ainult, katab API kiirjuhend autentimise ja auhinna loomise kutse, millest selle lõpp-punkti väljund pärineb.