Open Badges väljastamine WordPressist (ilma raske pluginata)

Kui sa haldad kursusi WordPressis, tunned protseduuri juba: keegi lõpetab mooduli LearnDashis, LifterLMS-is või Tutor LMS-is, LMS märgib ta „lõpetanuks” ja siis… ei juhtu midagi kontrollitavat. Ehk saadad PDF-i e-kirjaga. Ehk paigaldad spetsiaalse WordPressi märgiplugina, mis lisab omaenda andmebaasitabelid, omaenda pildikogu ja omaenda arusaama sellest, mis on „märk” — sellise, mida keegi väljaspool sinu saiti kontrollida ei saa.

On lihtsam tee. WordPressi kursuseplugin käivitab juba toimingu konksu (action hook) hetkel, mil keegi kursuse lõpetab. Selle konksu saad püüda ja teha ühe HTTP-päringu Badges Ninja API-le. Ei mingit lisapluginat, lisamajutust ega omanduslikku märgivormingut — ainult standarditele vastav Open Badge v2.0 volitus, mida saaja saab kontrollida kus iganes, lisada LinkedIni ja alla laadida PDF-ina.

See postitus käib mustri korra läbi ja näitab seejärel konkreetset konksu LearnDashi, LifterLMS-i ja Tutor LMS-i jaoks.

Miks mitte lihtsalt kasutada WordPressi märgipluginat?

Spetsiaalsed WordPressi märgipluginad lahendavad kitsama probleemi, kui esmapilgul paistab. Nad on head kuvama pilti sinu saidi „minu saavutused” lehel. Tavaliselt on nad palju nõrgemad asjades, mis volituse puhul tegelikult loevad:

• Ülekantavus. Märk, mis eksisteerib ainult lühikoodina (shortcode) sinu WordPressi saidil, ei ole volitus — see on kaunistus. Hetkel, mil saaja töökohta vahetab, oma postkasti vahetab või sinu sait maas on, kaob koos sellega ka „tõend”.
• Kontrollitavus. Igaüks peaks saama kontrollida, et volitus on ehtne, ilma sinu WordPressi haldusliidesesse sisse logimata. Open Badge v2.0 annab sulle disaini poolest avaliku kontroll-URL-i ja masinloetava JSON-LD-vormingu.
• Hooldatav pind. Iga WordPressi plugin on veel üks asi, mida parandada, veel üks andmebaasitabel, mida varundada, veel üks tõrkepunkt jumal-uuenduse ajal.

Väliseid API-t kutsudes kursuse lõpetamisel väldid kõiki kolme. WordPress jääb vastutama selle eest, milles ta hea on — sisu edastamine ja edenemise jälgimine —, ning volitus ise elab süsteemis, mis on ehitatud spetsiaalselt selle väljastamiseks, kontrollimiseks ja jagamiseks.

Muster: üks konks, üks HTTP-päring

Iga suurem WordPressi LMS-plugin käivitab toimingu, kui kasutaja kursuse lõpetab. Integratsioon koosneb alati samadest kolmest sammust:

1. Haaku kinni lõpetamise toimingust oma konkreetse LMS-i jaoks.
2. Otsi üles (või loo) saaja identiteet — tavaliselt lihtsalt tema WordPressi konto e-post ja kuvatav nimi.
3. Kutsu välja POST /awards Badges Ninja API-l funktsiooniga wp_remote_post(), edastades märgi ID ja saaja andmed.

Kõigepealt on sul vaja API-võtit. Genereeri see oma juhtpaneelilt jaotisest API Keys — täieliku juhendi leiad API-võtmete juhendist. Võtmed kuvatakse ainult üks kord, loomise ajal, seega salvesta see konstandina faili wp-config.php, mitte andmebaasi:

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

Hoia see võti serveripoolsena. Kõik selles juhendis töötab PHP-na sinu WordPressi serveris — wp_remote_post() on serveripoolne päring ja faili wp-config.php brauserisse kunagi ei saadeta. Just seda sa tahadki: võti liigub serverist serverisse HTTPS-i kaudu ja ükski külastaja ei saa seda lugeda. Ära kunagi vii seda päringut kliendipoolsesse JavaScripti — brauseri fetch()-päring võtmega otse koodis paljastaks selle igaühele brauseri arendustööriistade kaudu. Kaks harjumust tasub säilitada: veendu, et su majutaja serveerib faili wp-config.php täidetud PHP-na (mitte kunagi selgeteksti kujul) ega jäta veebijuure alla koopiat wp-config.php.bak, ning loo selle integratsiooni jaoks eraldi API-võti, et saaksid selle kompromiteerimise korral sõltumatult tühistada — ilma oma teisi tööriistu lõhkumata.

Jagatud abifunktsioon hoiab iga LMS-i konksu õhukesena:

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

Saaja e-posti aadress räsitakse serveripoolselt SHA-256-ga niipea, kui see jõuab Badges Ninjasse, ning tagastatav sisu sisaldab tunnustuse kontroll-URL-i — kasulik, kui soovid pärast päringu õnnestumist kohe WordPressis kuvada linki „vaata oma volitust”.

LearnDash

LearnDash käivitab learndash_course_completed ühe massiiviargumendiga, mis sisaldab user ja 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 );
} );

Märgi ID salvestamine kursuse metaandmetena (mitte ühe globaalse konstandina BADGES_NINJA_BADGE_ID) on õige valik niipea, kui sul on rohkem kui üks kursus — iga kursus seotakse oma märgikujundusega.

LifterLMS

LifterLMS käivitab lifterlms_course_completed argumentidega $user_id ja $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 käivitab tutor_course_complete_after kursuse ID-ga ja praeguse kasutaja tood välja seansist:

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

Kui sinu Tutor LMS-i seadistus käivitab lõpetamise taustaprotsessist (nt kviisi automaatse hindamise kaudu), asenda get_current_user_id() kasutaja ID-ga, mille sinu konkreetne konks pakub — kontrolli seadistamise ajal koormust ühe korra käsuga error_log( print_r( func_get_args(), true ) ), et argumendid kinnitada.

Märgi kujundamine enne konksu ühendamist

Enne kui midagi sellest käivitub, on sul vaja märki, mida välja anda. Visuaalne kujundaja katab selle ära ilma, et sa vajaksid kujundajat meeskonnas — üle 80 kujumalli, kohandatud värvid, ikoonikogu ja logo üleslaadimine, kõik ruudustikku klõpsates. Kui oled kujundajaga alles alustamas, käib Sinu esimese kontrollitava digitaalse tunnistuse kujundamine läbi malli valimise ja millegi väljastamise, mida saajad päriselt jagada tahavad.

Kui märk on olemas, võta selle ID juhtpaneelilt (või GET /badges kaudu) ja pane see oma kursuse kohandatud väljale.

Mida saaja tegelikult saab

See on osa, mida isetehtud WordPressi märgiplugin korrata ei suuda. Kui POST /awards õnnestub, saab saaja:

• Kordumatu kontroll-URL-i, mille saab avada igaüks — ilma WordPressi sisselogimiseta —, mis näitab, et volitus on ehtne, kes selle väljastas ja millal.
• QR-koodi ja A4-formaadis PDF-tunnistuse, mis genereeritakse automaatselt.
• Nupu Lisa LinkedIni profiilile, kui väljastajal on määratud LinkedIni organisatsiooni ID — ühekordse seadistuse leiad juhendist LinkedIni „lisa profiilile” nupu lisamine.
• Juurdepääsu oma saaja portaalile aadressil badges.ninja/me, maagilise lingiga sisselogimise kaudu — pole parooli, mida unustada, ega eraldi kontot, mida sinu WordPressi saidil hallata.
• Standarditele vastava Open Badge v2.0 JSON-LD-vormingu, mida saab kinnitada iga OB-teadlik kontrollija (mitte ainult Badges Ninja).

Miski sellest pole WordPressi ülesanne ehitada ja miski sellest ei tohiks elada ainult sinu WordPressi andmebaasis.

Rikete sujuv käsitlemine

Kursuse lõpetamise konksud käivituvad elava lehepäringu ajal ning aeglane või ebaõnnestunud API-päring ei tohiks blokeerida õppija „õnnitlused”-ekraani. Kaks praktilist kohandust, kui liigud edasi kontseptsiooni tõestamisest:

Ära lase ebaõnnestunud tunnustamisel kasutajaliidest blokeerida. Ülaltoodud abifunktsioon juba logib ja tagastab false, selle asemel et viga visata — LearnDash, LifterLMS ja Tutor jätkavad kõik oma tavapärast lõpetamise voogu olenemata sellest, mida badges_ninja_issue_award() tagastab.

Suuremas mahus pane see järjekorda, mitte ei kutsu otse. Kui juhid korraga suuri rühmi ühe kursuse läbi (rühma alguskuupäev, veebiseminari salvestuse avanemine), käivita konksust sünkroonse API-päringu asemel ajastatud WP-Cron sündmus:

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

See jaotab koormuse laiali ja hoiab ära, et üks aeglane päring saaks õppija probleemiks. Tõeliselt suurte partiide jaoks (terve varasem rühm, üle kantud korraga) jäta WordPressi konksu tee täielikult vahele ja kasuta massväljastamist CSV kaudu — laadi üles üks kord ja platvorm lehitseb väljastamist serveripoolselt koos sisseehitatud peatamise ja jätkamisega.

Märkus idempotentsuse kohta

Kui sinu LMS käivitab kunagi oma lõpetamise konksu sama kasutaja jaoks rohkem kui korra (levinud LearnDashi piirijuhtum kviiside uuestitegemisel või Tutor LMS-i uuestisünkroonimisel), ei taha sa sama märki kaks korda välja anda. Kõige lihtsam kaitse on WordPressi kasutaja metaandmete lipp, mille seadistad kohe pärast õnnestunud päringut:

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

Kui väljastad tõsiselt suures mahus ja soovid seda hallata tsentraalselt, mitte saidipõhiselt, vaata veebihaagi (webhook) põhist sündmuste käsitlust või täielikku API kiirjuhendit päringu ja vastuse kujude jaoks iga otspunkti kohta.

Kui muster kasvab ühest kursusest välja

Ülaltoodud näited eeldavad ühte märki kursuse kohta. Kui hakkad haldama virnastatavaid volitusi — mitme kursusemärgi järel avanevat rajamärki või lõpumärki, mis sõltub mitmest eeldusest —, vii mõte „milline märk, millise lõpetamise jaoks” postituse metaandmetest välja väiksesse otsingutabelisse või juhi seda tabelipõhisest automatiseeringust (Airtable või Google Sheets), mis käivitab sama POST /awards päringu. API-päring ise ei muutu — muutub ainult see, mis otsustab, millal seda teha.

Integratsiooni tõrkeotsing

Kimbuke probleeme põhjustab enamiku hõõrdumisest, millega inimesed selle esmakordsel ühendamisel kokku puutuvad:

Konks ei käivitu kunagi. Kinnita, et haagid õige toimingu külge oma pluginat tegeliku versiooni jaoks — eriti LearnDash on suuremate väljalasete lõikes lõpetamiskonksude nimesid muutnud (vanemad paigaldused toetuvad mõnikord ikka sellele, et learndash_course_completed käivitub teistsugusest koodirajast kui uuemates). Lisa oma tagasikutse algusesse ajutine error_log() ja jälgi faili wp-content/debug.log, samal ajal kui lõpetad testkursuse ühekordselt kasutatava kasutajana.

wp_remote_post() aegub. Jagatud majutuse keskkonnad blokeerivad mõnikord väljuvat HTTPS-i tundmatute hostide poole või piiravad päringute aegumisaega alla ülal seatud 15 sekundi. Kui päringud aeguvad järjekindlalt, kontrolli oma majutajaga, kas väljuvad ühendused hostiga api.badges.ninja on lubatud, ning kinnita, et sinu PHP-laiendil curl on ajakohased CA-sertifikaadid — vananenud sertifikaadikogum on levinud vaikiv rike vanematel jagatud majutuse pinudel.

400 Bad Request. Sisus puudub kohustuslik väli või on sel vale kuju. POST /awards eeldab badgeId-d, pesastatud objekti recipient väljadega name ja email ning ajatemplit issuedOn — ülaltoodud abifunktsioon saadab täpselt seda. Kõige levinum komistuskoht on saaja nimi: see peab olema vähemalt 5 tähemärki pikk, mistõttu WordPressi kuvatav nimi nagu „Jo” lükatakse tagasi. Kui kuvatav nimi on liiga lühike, kasuta selle asemel konto täisnime (või e-posti kohaliku osa).

401 Unauthorized. API-võtme konstant ei laadi või see genereeriti uuesti pärast konstandi seadistamist. Võtmed kuvatakse ainult üks kord, loomise ajal, ja neid ei saa hiljem uuesti tuua — kui oled kaotanud ülevaate, milline võti on aktiivne, kustuta vananenud võti ja väljasta uus, mitte ei arva.

Märk väljastati, aga vale märgikujundusega. See on peaaegu alati aegunud badges_ninja_badge_id postituse-metaandmete väärtus, mis jäi testimisest üle. Kuna kaardistus elab kursuse postituses, on lihtne unustada, et muutsid seda pärast kursuse dubleerimist uue rühma jaoks — tasub kiirelt üle kontrollida, kui iganes kursuse kloonid.

Korduvad tunnustused sama inimese jaoks. See on käsitletud ülal kasutaja metaandmete kaitsega, kuid väärib kordamist: LMS-i lõpetamiskonksud ei ole garanteeritud käivituma täpselt üks kord. Käsitle „juba tunnustatud” tavalise juhtumina, mida kontrollida, mitte erandliku juhtumina, mida ignoreerida.

Korduma kippuvad küsimused

Kas see töötab WooCommerce’i kursusepakettidega? Jah — kui paketi ostmine peaks käivitama märgi sõltumatult kursuse lõpetamisest (nt „sertifitseeritud liikme” märk igaühele, kes ostab konkreetse paketi), haagi woocommerce_order_status_completed külge LMS-i lõpetamistoimingu asemel ja otsi märgi ID toote metaandmetest, mitte kursuselt.

Kas saajad saavad märgi ilma WordPressi kontota? Jah, ja selles ongi mõte. Tunnustus on seotud nende e-posti aadressiga Badges Ninjas, mitte WordPressi kasutajakirjega. Kui sinu sait lubab külalisena ostmist või anonüümset kviisi lõpetamist, veendu lihtsalt, et salvestad tõelise e-posti aadressi, mille edastad funktsioonile badges_ninja_issue_award().

Mis siis, kui tahan tunnustusi enne väljasaatmist üle vaadata? Jäta päringu otsene käivitamine lõpetamiskonksust vahele. Selle asemel kirjuta ootel tunnustus (kasutaja, kursus, ajatempel) kohandatud tabelisse või postitustüüpi ning väljasta see ajastatud ülesandest või haldusnupust „Kinnita ja tunnusta”, mis kutsub sama abifunktsiooni nõudmisel.

Kas mul on vaja eraldi märki iga kursuse jaoks või saab üks märk katta mitu? Mõlemad töötavad. Mõned väljastajad loovad detailsuse huvides ühe märgi kursuse kohta; teised loovad ühe „programmi lõpetamise” märgi ja tunnustavad seda alles siis, kui kõik nõutud kursused on läbitud, kontrollides eelduste täitmist konksu sees enne API kutsumist.

---

Valmis väljastama oma esimest kontrollitavat volitust? Alusta tasuta aadressil badges.ninja — visuaalne kujundaja, avalik kontrollleht, PDF-tunnistus, Open Badge v2.0 väljund. Krediitkaarti pole vaja.