Izdavanje Open Badges iz WordPressa (bez glomaznog dodatka)

Ako vodite tečajeve na WordPressu, već znate kako to ide: netko završi modul u LearnDashu, LifterLMS-u ili Tutor LMS-u, LMS ga označi kao “završeno” i… ništa provjerljivo se ne dogodi. Možda pošaljete PDF e-poštom. Možda instalirate namjenski WordPress dodatak za značke koji dodaje vlastite tablice baze podataka, vlastitu knjižnicu slika i vlastitu ideju o tome što je “značka” — onu koju nitko izvan vaše stranice ne može provjeriti.

Postoji jednostavniji put. WordPress dodaci za tečajeve već pokreću action hook u trenutku kada netko završi tečaj. Taj hook možete uhvatiti i uputiti jedan HTTP poziv Badges Ninja API-ju. Bez dodatnog dodatka, bez dodatnog hostinga, bez vlasničkog formata značke — samo standardima usklađena Open Badge v2.0 vjerodajnica koju primatelj može provjeriti bilo gdje, dodati na LinkedIn i preuzeti kao PDF.

Ovaj članak prvo objašnjava obrazac, a zatim prikazuje konkretan hook za LearnDash, LifterLMS i Tutor LMS.

Zašto ne koristiti jednostavno WordPress dodatak za značke?

Namjenski WordPress dodaci za značke rješavaju uži problem nego što se čini na prvi pogled. Dobri su u prikazivanju slike na stranici “moja postignuća” unutar vaše stranice. Obično su znatno slabiji u onome što je zapravo bitno za vjerodajnicu:

Prenosivost. Značka koja postoji samo kao shortcode na vašoj WordPress stranici nije vjerodajnica — to je ukras. Čim primatelj promijeni posao, promijeni poštanski sandučić ili vaša stranica prestane raditi, “dokaz” nestaje s njom.
Provjera. Svatko bi trebao moći provjeriti da je vjerodajnica stvarna bez prijave u vašu WordPress administraciju. Open Badge v2.0 vam po dizajnu daje javni URL za provjeru i strojno čitljiv JSON-LD.
Površina za održavanje. Svaki WordPress dodatak je još jedna stvar koju treba zakrpati, još jedna tablica baze podataka koju treba sigurnosno kopirati, još jedna točka kvara tijekom nadogradnje jezgre.

Pozivanje vanjskog API-ja pri završetku tečaja zaobilazi sva tri problema. WordPress ostaje odgovoran za ono u čemu je dobar — isporuku sadržaja i praćenje napretka — a sama vjerodajnica živi u sustavu izgrađenom posebno za njezino izdavanje, provjeru i dijeljenje.

Obrazac: jedan hook, jedan HTTP poziv

Svaki veći WordPress LMS dodatak pokreće akciju kada korisnik završi tečaj. Integracija se uvijek sastoji od istih tri koraka:

Zakačite se na akciju završetka za vaš specifični LMS.
Pronađite (ili stvorite) identitet primatelja — obično samo e-poštu i prikazano ime njegovog WordPress računa.
Pozovite POST /awards na Badges Ninja API-ju pomoću wp_remote_post(), prosljeđujući ID značke i podatke primatelja.

Prvo će vam trebati API ključ. Generirajte ga s vaše nadzorne ploče pod API Keys — pogledajte vodič za API ključeve za potpuni prikaz postupka. Ključevi se prikazuju samo jednom pri stvaranju, stoga ga spremite u wp-config.php kao konstantu, a ne u bazu podataka:

define( 'BADGES_NINJA_API_KEY', 'bws_your_32_hex_key_here' );
define( 'BADGES_NINJA_BADGE_ID', 'your-badge-id' );

Novostvoreni ključ prikazan jednom

Ovaj ključ čuvajte na strani poslužitelja. Sve u ovom vodiču izvršava se u PHP-u na vašem WordPress poslužitelju — wp_remote_post() je poziv na strani poslužitelja, a wp-config.php se nikada ne šalje pregledniku. Upravo to i želite: ključ putuje od poslužitelja do poslužitelja preko HTTPS-a, a nijedan posjetitelj stranice ne može ga pročitati. Nikada ne premještajte ovaj poziv u JavaScript na strani klijenta — fetch() iz preglednika s ključem umetnutim u kod izložio bi ga bilo kome putem alata za razvojne programere u pregledniku. Vrijedi zadržati dvije navike: pobrinite se da vaš hosting poslužuje wp-config.php kao izvršeni PHP (nikada kao čisti tekst, i nemojte ostaviti kopiju wp-config.php.bak u webrootu), te izradite namjenski API ključ za ovu integraciju kako biste ga mogli neovisno opozvati ako ikada bude kompromitiran — bez narušavanja drugih vaših alata.

Zajednička pomoćna funkcija drži svaki LMS hook tankim:

function badges_ninja_issue_award( $recipient_email, $recipient_name, $badge_id ) {
	$response = wp_remote_post( 'https://api.badges.ninja/awards', array(
		'headers' => array(
			'X-Api-Key'    => BADGES_NINJA_API_KEY,
			'Content-Type' => 'application/json',
		),
		'body' => wp_json_encode( array(
			'badgeId'   => $badge_id,
			'recipient' => array(
				'name'  => $recipient_name,  // must be at least 5 characters
				'email' => $recipient_email,
			),
			'issuedOn'  => round( microtime( true ) * 1000 ), // epoch milliseconds
		) ),
		'timeout' => 15,
	) );
	if ( is_wp_error( $response ) ) {
		error_log( 'Badges Ninja award failed: ' . $response->get_error_message() );
		return false;
	}
	$code = wp_remote_retrieve_response_code( $response );
	if ( $code >= 400 ) {
		error_log( 'Badges Ninja award failed with HTTP ' . $code . ': ' . wp_remote_retrieve_body( $response ) );
		return false;
	}
	return json_decode( wp_remote_retrieve_body( $response ), true );
}

E-pošta primatelja hashira se SHA-256 algoritmom na strani poslužitelja čim stigne do Badges Ninja, a povratni odgovor uključuje URL za provjeru dodjele — korisno ako želite odmah nakon uspješnog poziva prikazati poveznicu “pogledaj svoju vjerodajnicu” izravno u WordPressu.

LearnDash

LearnDash pokreće learndash_course_completed s jednim argumentom tipa polje koji sadrži user i course:

add_action( 'learndash_course_completed', function( $data ) {
	$user   = $data['user'];
	$course = $data['course'];
	// Map LearnDash course ID → your Badges Ninja badge ID.
	// A simple approach: store the badge ID in a course custom field.
	$badge_id = get_post_meta( $course->ID, 'badges_ninja_badge_id', true );
	if ( ! $badge_id ) {
		return; // no badge configured for this course
	}
	badges_ninja_issue_award( $user->user_email, $user->display_name, $badge_id );
} );

Pohranjivanje ID-a značke kao meta podatka tečaja (umjesto jedne globalne konstante BADGES_NINJA_BADGE_ID) ispravan je potez čim imate više od jednog tečaja — svaki tečaj se mapira na vlastiti dizajn značke.

LifterLMS

LifterLMS pokreće lifterlms_course_completed s $user_id i $course_id:

add_action( 'lifterlms_course_completed', function( $user_id, $course_id ) {
	$user     = get_userdata( $user_id );
	$badge_id = get_post_meta( $course_id, 'badges_ninja_badge_id', true );
	if ( ! $user || ! $badge_id ) {
		return;
	}
	badges_ninja_issue_award( $user->user_email, $user->display_name, $badge_id );
}, 10, 2 );

Tutor LMS

Tutor LMS pokreće tutor_course_complete_after s ID-om tečaja, a trenutnog korisnika dohvaćate iz sesije:

add_action( 'tutor_course_complete_after', function( $course_id ) {
	$user_id  = get_current_user_id();
	$user     = get_userdata( $user_id );
	$badge_id = get_post_meta( $course_id, 'badges_ninja_badge_id', true );
	if ( ! $user || ! $badge_id ) {
		return;
	}
	badges_ninja_issue_award( $user->user_email, $user->display_name, $badge_id );
} );

Ako vaša Tutor LMS postavka pokreće završetak iz pozadinskog procesa (npr. putem automatskog ocjenjivanja kviza), zamijenite get_current_user_id() s ID-om korisnika koji vam pruža vaš specifični hook — provjerite sadržaj poziva pomoću error_log( print_r( func_get_args(), true ) ) jednom tijekom postavljanja kako biste potvrdili argumente.

Dizajniranje značke prije povezivanja hooka

Prije nego se bilo što od ovoga pokrene, trebate značku koju ćete dodijeliti. Vizualni dizajner to pokriva bez potrebe za dizajnerom u timu — više od 80 predložaka oblika, prilagođene boje, knjižnica ikona i učitavanje logotipa, sve s pripajanjem na mrežu (snap-to-grid). Ako ste novi u dizajneru, Dizajniranje vašeg prvog provjerljivog digitalnog certifikata vodi vas kroz odabir predloška i objavu nečega što će primatelji zaista željeti podijeliti.

Kada značka postoji, preuzmite njezin ID s nadzorne ploče (ili putem GET /badges) i unesite ga u prilagođeno polje vašeg tečaja.

Što primatelj zapravo dobiva

Ovo je dio koji domaći WordPress dodatak za značke ne može replicirati. Kada POST /awards uspije, primatelj dobiva:

Jedinstveni URL za provjeru koji svatko može otvoriti — bez potrebe za prijavom na WordPress — koji pokazuje da je vjerodajnica stvarna, tko ju je izdao i kada.
QR kod i A4 PDF certifikat, generirane automatski.
Gumb Dodaj na LinkedIn profil, ako vaš izdavatelj ima postavljen ID LinkedIn organizacije — pogledajte Dodavanje LinkedIn gumba “Dodaj na profil” za jednokratno postavljanje.
Pristup vlastitom portalu za primatelje na badges.ninja/me, putem prijave čarobnom poveznicom — bez lozinke koju treba zapamtiti, bez zasebnog računa za upravljanje na vašoj WordPress stranici.
Standardima usklađen Open Badge v2.0 JSON-LD, tako da ga bilo koji verifikator svjestan OB formata (ne samo Badges Ninja) može validirati.

Ništa od toga nije zadaća WordPressa da izgradi, i ništa od toga ne bi trebalo živjeti samo unutar vaše WordPress baze podataka.

Elegantno rukovanje neuspjesima

Hookovi za završetak tečaja pokreću se tijekom uživo zahtjeva za stranicom, a spor ili neuspješan API poziv ne bi trebao blokirati polaznikov ekran “čestitamo”. Dva praktična prilagođavanja nakon što prijeđete fazu dokazivanja koncepta:

Ne dopustite da neuspjela dodjela blokira sučelje. Gore navedena pomoćna funkcija već zapisuje u dnevnik i vraća false umjesto bacanja iznimke — LearnDash, LifterLMS i Tutor svi nastavljaju svoj uobičajeni tijek završetka bez obzira na to što vraća badges_ninja_issue_award().

U velikom opsegu, stavite ju u red umjesto izravnog pozivanja. Ako provodite velike kohorte kroz jedan tečaj odjednom (datum početka kohorte, otključavanje snimke webinara), pokrenite zakazani WP-Cron događaj iz hooka umjesto sinkronog pozivanja API-ja:

add_action( 'learndash_course_completed', function( $data ) {
	wp_schedule_single_event( time() + 30, 'badges_ninja_deferred_award', array(
		$data['user']->user_email,
		$data['user']->display_name,
		get_post_meta( $data['course']->ID, 'badges_ninja_badge_id', true ),
	) );
} );
add_action( 'badges_ninja_deferred_award', 'badges_ninja_issue_award', 10, 3 );

To raspoređuje opterećenje i sprječava da jedan spor zahtjev postane polaznikov problem. Za istinski velike serije (cijela prošla kohorta, migrirana odjednom), potpuno preskočite put s WordPress hookom i koristite masovnu dodjelu putem CSV-a — učitajte jednom, a platforma paginira izdavanje na strani poslužitelja s ugrađenom pauzom/nastavkom.

Napomena o idempotenciji

Ako vaš LMS ikada pokrene svoj hook za završetak više od jednom za istog korisnika (uobičajen rubni slučaj u LearnDashu kod ponovnih pokušaja kviza, ili ponovna sinkronizacija u Tutor LMS-u), ne želite dodijeliti istu značku dvaput. Najjednostavnija zaštita je oznaka u WordPress korisničkim meta podacima koju postavite odmah nakon uspješnog poziva:

if ( get_user_meta( $user_id, 'badges_ninja_awarded_' . $course_id, true ) ) {
	return; // already issued
}
$result = badges_ninja_issue_award( $user->user_email, $user->display_name, $badge_id );
if ( $result ) {
	update_user_meta( $user_id, 'badges_ninja_awarded_' . $course_id, true );
}

Ako izdajete u stvarno velikom opsegu i želite da se to obrađuje centralizirano umjesto po stranici, pogledajte rukovanje događajima putem webhookova ili potpuni brzi početak s API-jem za oblike zahtjeva/odgovora za svaku krajnju točku.

Kada ovaj obrazac naraste iznad jednog tečaja

Gornji primjeri pretpostavljaju jednu značku po tečaju. Kada počnete koristiti slagajuće vjerodajnice — značku staze koja se otključava nakon nekoliko značaka tečaja, ili završnu značku koja ovisi o više preduvjeta — premjestite mapiranje “koja značka, za koji završetak” iz meta podataka objave u malu tablicu za pretraživanje, ili ga pokrenite iz automatizacije temeljene na proračunskoj tablici (Airtable ili Google Sheets) koja pokreće isti poziv POST /awards. Sam API poziv se ne mijenja; mijenja se samo ono što odlučuje kada ga treba uputiti.

Rješavanje problema s integracijom

Nekoliko problema čini najveći dio poteškoća s kojima se ljudi susreću prilikom prvog povezivanja ovoga:

Hook se nikada ne pokreće. Potvrdite da se kačite na ispravnu akciju za stvarnu verziju vašeg dodatka — LearnDash je posebno mijenjao nazive hookova za završetak kroz glavna izdanja (starije instalacije ponekad se i dalje oslanjaju na learndash_course_completed koji se pokreće iz drugačije putanje koda nego u novijima). Dodajte privremeni error_log() na vrh vaše povratne funkcije i pratite wp-content/debug.log dok kao odbacivog testnog korisnika završavate testni tečaj.

wp_remote_post() istječe. Okruženja dijeljenog hostinga ponekad blokiraju odlazni HTTPS prema nepoznatim poslužiteljima, ili ograničavaju vremenska ograničenja zahtjeva ispod gore postavljenih 15 sekundi. Ako pozivi dosljedno istječu, provjerite kod vašeg pružatelja hostinga jesu li dopuštene odlazne veze prema api.badges.ninja, i potvrdite da vaša PHP ekstenzija curl ima ažurne CA certifikate — zastarjeli paket certifikata čest je tihi uzrok neuspjeha na starijim platformama dijeljenog hostinga.

400 Bad Request. Sadržaju nedostaje obavezno polje ili ima pogrešan oblik. POST /awards očekuje badgeId, ugniježđeni objekt recipient s name i email, te vremensku oznaku issuedOn — gore navedena pomoćna funkcija šalje upravo to. Najčešća zamka je ime primatelja: mora imati najmanje 5 znakova, pa se WordPress prikazano ime poput “Jo” odbija. Vratite se na puno ime računa (ili dio e-pošte prije @) kada je prikazano ime prekratko.

401 Unauthorized. Konstanta API ključa se ne učitava, ili je regenerirana nakon što je konstanta postavljena. Ključevi se prikazuju samo jednom pri stvaranju i ne mogu se ponovno dohvatiti — ako ste izgubili trag koji je ključ aktivan, izbrišite zastarjeli i izdajte novi umjesto nagađanja.

Značka izdana, ali s pogrešnim dizajnom. To je gotovo uvijek zastarjela vrijednost meta podatka objave badges_ninja_badge_id preostala od testiranja. Budući da mapiranje živi na objavi tečaja, lako je zaboraviti da ste ga promijenili nakon dupliciranja tečaja za novu kohortu — vrijedi brza provjera svaki put kad klonirate tečaj.

Duplicirane dodjele za istu osobu. Pokriveno gore zaštitom putem korisničkih meta podataka, ali vrijedi ponoviti: nije zajamčeno da će se hookovi za završetak LMS-a pokrenuti točno jednom. Tretirajte “već dodijeljeno” kao uobičajen slučaj koji treba provjeriti, a ne kao rubni slučaj koji se ignorira.

Često postavljana pitanja

Radi li ovo s WooCommerce paketima tečajeva? Da — ako bi kupnja paketa trebala pokrenuti značku neovisno o završetku tečaja (npr. značka “certificirani član” za svakoga tko kupi određeni paket), zakačite se na woocommerce_order_status_completed umjesto na akciju završetka LMS-a, i potražite ID značke iz meta podataka proizvoda umjesto tečaja.

Mogu li primatelji dobiti značku bez WordPress računa? Da, i to je upravo svrha. Dodjela je vezana uz njihovu adresu e-pošte u Badges Ninja, a ne uz WordPress korisnički zapis. Ako vaša stranica dopušta kupnju kao gost ili anonimni završetak kviza, samo se pobrinite da bilježite stvarnu adresu e-pošte koju prosljeđujete u badges_ninja_issue_award().

Što ako želim pregledati dodjele prije nego što se pošalju? Preskočite izravno pokretanje poziva iz hooka za završetak. Umjesto toga, zapišite dodjelu na čekanju (korisnik, tečaj, vremenska oznaka) u prilagođenu tablicu ili tip objave, i izdajte ju putem zakazanog zadatka ili administratorskog gumba “Odobri i dodijeli” koji na zahtjev poziva istu pomoćnu funkciju.

Trebam li zasebnu značku za svaki tečaj, ili jedna značka može pokriti nekoliko njih? Oba pristupa funkcioniraju. Neki izdavatelji stvaraju jednu značku po tečaju radi granularnosti; drugi stvaraju jedinstvenu značku “završetka programa” i dodjeljuju ju tek kada je svaki obavezni tečaj završen, provjeravajući završetak preduvjeta unutar hooka prije pozivanja API-ja.

Spremni izdati svoju prvu provjerljivu vjerodajnicu? Započnite besplatno na badges.ninja — vizualni dizajner, javna stranica za provjeru, PDF certifikat, Open Badge v2.0 izlaz. Kreditna kartica nije potrebna.