Izdajanje digitalnih značk Open Badges iz WordPressa (brez zahtevnega vtičnika)

Če vodite tečaje na WordPressu, že poznate potek: nekdo zaključi modul v LearnDashu, LifterLMS-u ali Tutor LMS-u, LMS ga označi kot »zaključil«, nato pa … se ne zgodi nič preverljivega. Morda pošljete PDF po e-pošti. Morda namestite namenski WordPress vtičnik za značke, ki doda svoje lastne tabele v podatkovni bazi, svojo knjižnico slik in svojo predstavo o tem, kaj je »značka« — takšno, ki je nihče zunaj vašega spletnega mesta ne more preveriti.

Obstaja preprostejša pot. WordPress vtičniki za tečaje že sprožijo kljuko dejanja (action hook) v trenutku, ko nekdo zaključi tečaj. To kljuko lahko ujamete in izvedete en sam klic HTTP na API Badges Ninja. Brez dodatnega vtičnika, brez dodatnega gostovanja, brez lastniškega formata značk — le standardom skladno poverilo Open Badge v2.0, ki ga lahko prejemnik preveri kjer koli, doda na LinkedIn in prenese kot PDF.

Ta prispevek najprej predstavi vzorec, nato pa pokaže konkretno kljuko za LearnDash, LifterLMS in Tutor LMS.

Zakaj ne uporabiti kar WordPress vtičnika za značke?

Namenski WordPress vtičniki za značke rešujejo ožji problem, kot se zdi na prvi pogled. Dobri so pri prikazu slike na strani »moji dosežki« znotraj vašega spletnega mesta. Običajno pa so bistveno šibkejši pri stvareh, ki so za poverilo dejansko pomembne:

• Prenosljivost. Značka, ki obstaja le kot kratka koda (shortcode) na vašem WordPress spletnem mestu, ni poverilo — je okras. V trenutku, ko prejemnik zamenja službo, spremeni svoj poštni predal ali vaše spletno mesto preneha delovati, izgine tudi »dokaz«.
• Preverjanje. Vsakdo bi moral biti sposoben preveriti, da je poverilo pristno, ne da bi se prijavil v vašo WordPress administracijo. Open Badge v2.0 po zasnovi ponuja javni URL za preverjanje in strojno berljiv JSON-LD.
• Obseg vzdrževanja. Vsak WordPress vtičnik je še ena stvar, ki jo je treba popravljati, še ena tabela v podatkovni bazi, ki jo je treba varnostno kopirati, še ena točka odpovedi ob posodobitvi jedra.

Klic zunanjega API-ja ob zaključku tečaja se izogne vsem trem težavam. WordPress ostane odgovoren za tisto, v čemer je dober — dostavo vsebine in sledenje napredku —, poverilo samo pa živi v sistemu, zgrajenem posebej za njegovo izdajanje, preverjanje in deljenje.

Vzorec: ena kljuka, en klic HTTP

Vsak večji WordPress LMS vtičnik sproži dejanje, ko uporabnik zaključi tečaj. Integracija je vedno sestavljena iz istih treh korakov:

1. Priključite se na dejanje zaključka za vaš konkretni LMS.
2. Poiščite (ali ustvarite) identiteto prejemnika — običajno gre le za e-poštni naslov in prikazno ime njegovega WordPress računa.
3. Pokličite POST /awards na API-ju Badges Ninja z uporabo wp_remote_post(), pri čemer posredujete ID značke in podatke o prejemniku.

Najprej boste potrebovali API ključ. Ustvarite ga na nadzorni plošči pod API Keys — celoten vodnik najdete v vodniku po API ključih. Ključi se prikažejo samo enkrat, ob ustvarjanju, zato jih shranite v wp-config.php kot konstanto, ne v podatkovno bazo:

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

Ta ključ ohranite na strani strežnika. Vse v tem vodniku teče v PHP-ju na vašem WordPress strežniku — wp_remote_post() je klic na strani strežnika, wp-config.php pa nikoli ni poslan brskalniku. Prav to je tisto, kar želite: ključ potuje od strežnika do strežnika prek HTTPS, noben obiskovalec spletnega mesta pa ga ne more prebrati. Tega klica nikoli ne premaknite v odjemalski JavaScript — fetch() iz brskalnika s ključem, vpisanim neposredno v kodo, bi ga razkril vsakomur prek razvijalskih orodij njegovega brskalnika. Dve navadi sta vredni ohranjanja: prepričajte se, da vaš gostitelj wp-config.php streže kot izvedeno PHP kodo (nikoli kot navadno besedilo) in da v korenu spletnega mesta ne pustite kopije wp-config.php.bak, ter ustvarite namensko API ključ za to integracijo, da ga lahko ob morebitni ogroženosti prekličete neodvisno — ne da bi pri tem pokvarili druga orodja.

Skupna pomožna funkcija poskrbi, da ostane vsaka kljuka LMS-a preprosta:

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štni naslov prejemnika je enkrat hashiran s SHA-256 na strani strežnika, ko doseže Badges Ninja, vrnjeni odgovor pa vključuje URL za preverjanje priznanja — priročno, če želite v WordPressu takoj po uspešnem klicu prikazati povezavo »oglejte si svoje poverilo«.

LearnDash

LearnDash sproži learndash_course_completed z enim samim argumentom polja, ki vsebuje user in 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 );
} );

Shranjevanje ID-ja značke kot meta podatka tečaja (namesto ene same globalne konstante BADGES_NINJA_BADGE_ID) je pravilna odločitev, ko imate več kot en tečaj — vsak tečaj se preslika v svojo lastno zasnovo značke.

LifterLMS

LifterLMS sproži lifterlms_course_completed z argumentoma $user_id in $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 sproži tutor_course_complete_after z ID-jem tečaja, trenutnega uporabnika pa pridobite iz seje:

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

Če vaša namestitev Tutor LMS sproži zaključek iz ozadnjega procesa (npr. prek samodejnega ocenjevanja kviza), zamenjajte get_current_user_id() z ID-jem uporabnika, ki ga ponuja vaša konkretna kljuka — ob nastavitvi enkrat preverite vsebino s error_log( print_r( func_get_args(), true ) ), da potrdite argumente.

Zasnova značke, preden priklopite kljuko

Preden se karkoli od tega sproži, potrebujete značko, ki jo boste podelili. Vizualni oblikovalnik to pokrije, ne da bi potrebovali oblikovalca v ekipi — več kot 80 predlog oblik, poljubne barve, knjižnica ikon in nalaganje logotipa, vse z lepljenjem na mrežo. Če ste novi pri oblikovalniku, vas Oblikovanje vašega prvega preverljivega digitalnega potrdila popelje skozi izbiro predloge in objavo nečesa, kar bodo prejemniki dejansko želeli deliti.

Ko značka obstaja, njen ID pridobite na nadzorni plošči (ali prek GET /badges) in ga vnesite v poljubno polje tečaja.

Kaj prejemnik dejansko dobi

To je del, ki ga doma narejen WordPress vtičnik za značke ne more posnemati. Ko POST /awards uspe, prejemnik dobi:

• Edinstven URL za preverjanje, ki ga lahko odpre kdor koli — brez prijave v WordPress — in ki pokaže, da je poverilo pristno, kdo ga je izdal in kdaj.
• QR kodo in potrdilo v obliki PDF A4, ustvarjena samodejno.
• Gumb Dodaj v profil LinkedIn, če ima vaš izdajatelj nastavljen ID organizacije LinkedIn — za enkratno nastavitev glejte Dodajte gumb »Dodaj v profil« za LinkedIn.
• Dostop do lastnega portala za prejemnike na naslovu badges.ninja/me, prek prijave z magično povezavo — brez gesla, ki bi ga bilo treba pozabiti, in brez ločenega računa, ki bi ga bilo treba upravljati na vašem WordPress spletnem mestu.
• Standardom skladen Open Badge v2.0 JSON-LD, ki ga lahko preveri kateri koli preverjevalnik, ki pozna OB (ne le Badges Ninja).

Nič od tega ni naloga WordPressa in nič od tega ne bi smelo obstajati zgolj v vaši WordPress podatkovni bazi.

Elegantno obvladovanje napak

Kljuke za zaključek tečaja se sprožijo med živo zahtevo za stran, počasen ali neuspešen klic API-ja pa ne bi smel blokirati učenčevega zaslona »čestitke«. Ko preidete onkraj poskusnega koncepta, sta smiselni dve praktični prilagoditvi:

Ne dovolite, da neuspešna podelitev blokira uporabniški vmesnik. Zgornja pomožna funkcija že beleži napako in vrne false, namesto da bi jo vrgla — LearnDash, LifterLMS in Tutor vsi nadaljujejo svoj običajni potek zaključka ne glede na to, kaj vrne badges_ninja_issue_award().

V večjem obsegu jo postavite v čakalno vrsto, namesto da jo pokličete neposredno. Če hkrati vodite velike skupine skozi en sam tečaj (datum začetka skupine, odklepanje posnetka spletnega seminarja), namesto sinhronega klica API-ja sprožite iz kljuke načrtovan dogodek WP-Cron:

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 porazdeli obremenitev in prepreči, da bi ena sama počasna zahteva postala učenčeva težava. Za resnično velike serije (celotna pretekla skupina, preseljena naenkrat) v celoti preskočite pot prek WordPress kljuke in uporabite množično podeljevanje prek CSV — naložite enkrat, platforma pa izdajanje na strani strežnika strani po strani izvede z vgrajenim premorom in nadaljevanjem.

Opomba o idempotentnosti

Če vaš LMS kdaj sproži svojo kljuko zaključka več kot enkrat za istega uporabnika (pogost robni primer pri LearnDashu s ponovnim opravljanjem kvizov ali pri ponovni sinhronizaciji Tutor LMS), ne želite podeliti iste značke dvakrat. Najpreprostejša zaščita je zastavica v meta podatkih WordPress uporabnika, ki jo nastavite takoj po uspešnem klicu:

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

Če izdajate v resnično velikem obsegu in želite to obravnavati centralno namesto na vsakem spletnem mestu posebej, si oglejte obravnavo dogodkov prek webhookov ali celoten hitri začetek API-ja za oblike zahtev in odgovorov za vsako končno točko.

Ko ta vzorec preraste en sam tečaj

Zgornji primeri predpostavljajo eno značko na tečaj. Ko upravljate zložljiva poverila — značko za pot, ki se odklene po več značkah za tečaje, ali zaključno značko, ki je odvisna od več predpogojev — preslikavo »katera značka za kateri zaključek« premaknite iz meta podatkov objave v majhno iskalno tabelo ali jo poganjajte iz avtomatizacije, ki temelji na preglednici (Airtable ali Google Sheets) in sproži isti klic POST /awards. Klic API-ja sam se ne spremeni — spremeni se le, kaj odloča, kdaj ga izvesti.

Odpravljanje težav pri integraciji

Peščica težav je odgovorna za večino trenja, s katerim se ljudje srečajo ob prvem povezovanju te integracije:

Kljuka se nikoli ne sproži. Preverite, ali se priklapljate na pravilno dejanje za dejansko različico svojega vtičnika — LearnDash je zlasti spreminjal imena kljuk za zaključek med večjimi izdajami (starejše namestitve se včasih še vedno zanašajo na to, da se learndash_course_completed sproži po drugačni poti kode kot pri novejših). Na vrh svojega povratnega klica dodajte začasen error_log() in med zaključevanjem testnega tečaja kot uporabnik za enkratno uporabo spremljajte wp-content/debug.log.

wp_remote_post() doseže časovno omejitev. Okolja skupnega gostovanja včasih blokirajo odhodni HTTPS do nepoznanih gostiteljev ali omejijo časovne omejitve zahtev pod zgoraj nastavljenih 15 sekund. Če klici dosledno dosežejo časovno omejitev, pri svojem gostitelju preverite, ali so odhodne povezave do api.badges.ninja dovoljene, in potrdite, da ima vaša PHP razširitev curl posodobljene korenske certifikate CA — zastarel sveženj potrdil je pogosta tiha napaka na starejših skladih skupnega gostovanja.

400 Bad Request. V vsebini manjka obvezno polje ali pa ima napačno obliko. POST /awards pričakuje badgeId, vgnezden objekt recipient z name in email ter časovni žig issuedOn — zgornja pomožna funkcija pošlje natanko to. Najpogostejša zatikanica je prejemnikovo ime: dolgo mora biti vsaj 5 znakov, zato je WordPress prikazno ime, kot je »Jo«, zavrnjeno. Če je prikazno ime prekratko, uporabite polno ime računa (ali del e-poštnega naslova pred @).

401 Unauthorized. Konstanta API ključa se ne naloži ali pa je bila ponovno ustvarjena, potem ko je bila konstanta že nastavljena. Ključi se prikažejo samo enkrat, ob ustvarjanju, in jih kasneje ni mogoče znova pridobiti — če ste izgubili pregled nad tem, kateri ključ je aktiven, zastarelega izbrišite in izdajte novega, namesto da ugibate.

Značka je izdana, vendar z napačno zasnovo. To je skoraj vedno zastarela vrednost meta podatka badges_ninja_badge_id, ki je ostala od testiranja. Ker preslikava obstaja na objavi tečaja, je zlahka spregledati, da ste jo spremenili po podvojitvi tečaja za novo skupino — vredno je hiter pregled ob vsakem kloniranju tečaja.

Podvojene podelitve za isto osebo. To je obravnavano zgoraj z zaščito prek meta podatkov uporabnika, vendar velja ponoviti: kljuke za zaključek LMS-a niso zagotovljeno sprožene natanko enkrat. »Že podeljeno« obravnavajte kot običajen primer, ki ga je treba preveriti, ne kot robni primer, ki ga je mogoče spregledati.

Pogosta vprašanja

Ali to deluje s paketi tečajev WooCommerce? Da — če naj nakup paketa sproži značko neodvisno od zaključka tečaja (npr. značko »certificiran član« za vsakogar, ki kupi določen paket), se priklopite na woocommerce_order_status_completed namesto na dejanje zaključka LMS-a, ID značke pa poiščite v meta podatkih izdelka namesto tečaja.

Ali lahko prejemniki dobijo značko brez WordPress računa? Da, in prav to je bistvo. Podelitev je vezana na njihov e-poštni naslov v Badges Ninja, ne na zapis WordPress uporabnika. Če vaše spletno mesto omogoča nakup kot gost ali anonimen zaključek kviza, le poskrbite, da zajamete pravi e-poštni naslov, ki ga posredujete funkciji badges_ninja_issue_award().

Kaj, če želim podelitve pregledati, preden gredo ven? Preskočite neposreden klic iz kljuke zaključka. Namesto tega zapišite čakajočo podelitev (uporabnik, tečaj, časovni žig) v prilagojeno tabelo ali vrsto objave in jo izdajte iz načrtovane naloge ali skrbniškega gumba »Odobri in podeli«, ki na zahtevo pokliče isto pomožno funkcijo.

Ali potrebujem ločeno značko za vsak tečaj, ali lahko ena pokrije več tečajev? Oboje deluje. Nekateri izdajatelji ustvarijo eno značko na tečaj zaradi podrobnosti; drugi ustvarijo eno samo značko »zaključek programa« in jo podelijo šele, ko so opravljeni vsi zahtevani tečaji, s preverjanjem izpolnjenih predpogojev znotraj kljuke pred klicem API-ja.

---

Ste pripravljeni izdati svoje prvo preverljivo poverilo? Začnite brezplačno na badges.ninja — vizualni oblikovalnik, javna stran za preverjanje, potrdilo v obliki PDF, izhod Open Badge v2.0. Brez potrebne kreditne kartice.