Vydávanie Open Badges z WordPressu (bez ťažkého pluginu)

Ak prevádzkujete kurzy na WordPresse, poznáte tento postup: niekto dokončí modul v LearnDash-i, LifterLMS-e alebo Tutor LMS-e, LMS ho označí ako „dokončené” a potom… sa nič overiteľné nestane. Možno pošlete PDF e-mailom. Možno nainštalujete samostatný WordPress plugin na odznaky, ktorý pridá vlastné tabuľky v databáze, vlastnú knižnicu obrázkov a vlastnú predstavu o tom, čo je „odznak” — takú, ktorú nikto mimo vášho webu nedokáže overiť.

Existuje jednoduchšia cesta. WordPress pluginy pre kurzy už v okamihu, keď niekto dokončí kurz, spúšťajú action hook. Tento hook môžete zachytiť a urobiť jedno HTTP volanie na Badges Ninja API. Žiadny ďalší plugin, žiadny ďalší hosting, žiadny vlastný formát odznaku — len štandardizovaný Open Badge v2.0 certifikát, ktorý si príjemca môže overiť kdekoľvek, pridať na LinkedIn a stiahnuť ako PDF.

Tento článok si najprv prejde vzor všeobecne a potom ukáže konkrétny hook pre LearnDash, LifterLMS a Tutor LMS.

Prečo jednoducho nepoužiť WordPress plugin na odznaky?

Špecializované WordPress pluginy na odznaky riešia užší problém, než sa na prvý pohľad zdá. Sú dobré v zobrazovaní obrázka na stránke „moje úspechy” vo vnútri vášho webu. Zvyčajne sú oveľa slabšie v tom, na čom pri certifikáte skutočne záleží:

• Prenositeľnosť. Odznak, ktorý existuje len ako shortcode na vašom WordPress webe, nie je certifikát — je to dekorácia. V okamihu, keď príjemca zmení zamestnanie, zmení si e-mailovú schránku, alebo váš web prestane fungovať, „dôkaz” zmizne spolu s ním.
• Overenie. Ktokoľvek by mal vedieť overiť, že certifikát je skutočný, bez prihlásenia do administrácie vášho WordPressu. Open Badge v2.0 vám dizajnovo dáva verejnú URL adresu na overenie a strojovo čitateľné JSON-LD.
• Povrch údržby. Každý WordPress plugin je ďalšia vec na záplatovanie, ďalšia databázová tabuľka na zálohovanie, ďalší bod zlyhania počas aktualizácie jadra.

Volanie externého API pri dokončení kurzu obchádza všetky tri problémy. WordPress zostáva zodpovedný za to, v čom je dobrý — doručovanie obsahu a sledovanie postupu — a samotný certifikát žije v systéme postavenom špeciálne na jeho vydávanie, overovanie a zdieľanie.

Vzor: jeden hook, jedno HTTP volanie

Každý väčší WordPress LMS plugin spustí akciu, keď používateľ dokončí kurz. Integrácia má vždy rovnaké tri kroky:

1. Zachyťte akciu dokončenia pre váš konkrétny LMS.
2. Nájdite (alebo vytvorte) identitu príjemcu — zvyčajne len e-mail a zobrazované meno jeho WordPress účtu.
3. Zavolajte POST /awards na Badges Ninja API pomocou wp_remote_post() s ID odznaku a údajmi o príjemcovi.

Najprv budete potrebovať API kľúč. Vygenerujte ho vo svojom dashboarde v sekcii API Keys — kompletný postup nájdete v sprievodcovi API kľúčmi. Kľúče sa zobrazia iba raz pri vytvorení, preto ho uložte do wp-config.php ako konštantu, nie do databázy:

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

Tento kľúč držte na strane servera. Všetko v tomto návode beží v PHP na vašom WordPress serveri — wp_remote_post() je volanie na strane servera a wp-config.php sa nikdy neposiela do prehliadača. Presne to chcete: kľúč cestuje zo servera na server cez HTTPS a žiadny návštevník webu si ho nemôže prečítať. Nikdy nepresúvajte toto volanie do klientského JavaScriptu — fetch() z prehliadača s vloženým kľúčom by ho odhalil komukoľvek prostredníctvom vývojárskych nástrojov prehliadača. Oplatí sa dodržiavať dva návyky: uistite sa, že váš hosting podáva wp-config.php ako vykonávaný PHP (nikdy ako čistý text, a nenechávajte v koreňovom adresári webu kópiu wp-config.php.bak), a vytvorte pre túto integráciu vyhradený API kľúč, aby ste ho v prípade kompromitácie mohli odvolať nezávisle — bez narušenia ostatných nástrojov.

Zdieľaná pomocná funkcia udržiava každý LMS hook stručný:

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-mail príjemcu sa hneď po doručení do Badges Ninja hashuje na strane servera pomocou SHA-256 a vrátený payload obsahuje URL adresu na overenie odznaku — užitočné, ak chcete po úspešnom volaní priamo vo WordPresse zobraziť odkaz „zobraziť svoj certifikát”.

LearnDash

LearnDash spúšťa learndash_course_completed s jedným argumentom typu pole, ktorý obsahuje user a 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 );
} );

Uloženie ID odznaku ako vlastného poľa kurzu (namiesto jednej globálnej konštanty BADGES_NINJA_BADGE_ID) je správne riešenie, hneď ako máte viac než jeden kurz — každý kurz sa mapuje na vlastný dizajn odznaku.

LifterLMS

LifterLMS spúšťa lifterlms_course_completed s $user_id a $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 spúšťa tutor_course_complete_after s ID kurzu a aktuálneho používateľa získate zo session:

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

Ak vaša konfigurácia Tutor LMS spúšťa dokončenie z procesu na pozadí (napr. cez automatické hodnotenie testu), nahraďte get_current_user_id() ID používateľa, ktoré poskytuje váš konkrétny hook — payload si raz počas nastavovania overte pomocou error_log( print_r( func_get_args(), true ) ), aby ste potvrdili argumenty.

Navrhnutie odznaku pred zapojením hooku

Skôr než sa čokoľvek z tohto spustí, potrebujete odznak, ktorý budete udeľovať. Vizuálny dizajnér to pokrýva bez potreby dizajnéra v tíme — vyše 80 šablón tvarov, vlastné farby, knižnica ikon a nahrávanie loga, všetko s prichytávaním na mriežku. Ak s dizajnérom začínate, Návrh vášho prvého overiteľného digitálneho certifikátu vás prevedie výberom šablóny a vytvorením niečoho, čo budú príjemcovia naozaj chcieť zdieľať.

Keď odznak existuje, získajte jeho ID z dashboardu (alebo cez GET /badges) a vložte ho do vlastného poľa vášho kurzu.

Čo príjemca skutočne dostane

Toto je časť, ktorú domácky vyrobený WordPress plugin na odznaky nedokáže nahradiť. Keď POST /awards uspeje, príjemca dostane:

• Jedinečnú URL adresu na overenie, ktorú môže otvoriť ktokoľvek — bez potreby prihlásenia do WordPressu — ukazujúcu, že certifikát je skutočný, kto ho vydal a kedy.
• QR kód a PDF certifikát vo formáte A4, generované automaticky.
• Tlačidlo Add to LinkedIn Profile, ak má váš vydavateľ nastavené LinkedIn organization ID — jednorazové nastavenie nájdete v Pridanie tlačidla „Add to Profile” pre LinkedIn.
• Prístup do vlastného portálu pre príjemcov na badges.ninja/me, prostredníctvom prihlásenia cez magic-link — žiadne heslo na zapamätanie, žiadny samostatný účet na spravovanie na vašom WordPress webe.
• Štandardizované Open Badge v2.0 JSON-LD, takže ho dokáže overiť ktorýkoľvek verifikátor podporujúci OB (nielen Badges Ninja).

Nič z toho nie je úlohou WordPressu vybudovať a nič z toho by nemalo žiť iba vo vašej WordPress databáze.

Elegantné zvládanie zlyhaní

Hooky pre dokončenie kurzu sa spúšťajú počas živej požiadavky na stránku a pomalé alebo neúspešné API volanie by nemalo blokovať „gratulujeme” obrazovku študenta. Dve praktické úpravy, keď sa posuniete za rámec proof of concept:

Nedovoľte, aby neúspešné udelenie zablokovalo rozhranie. Pomocná funkcia vyššie už loguje a vracia false namiesto vyvolania výnimky — LearnDash, LifterLMS a Tutor pokračujú vo svojom bežnom priebehu dokončenia bez ohľadu na to, čo vráti badges_ninja_issue_award().

Vo väčšom rozsahu ho radšej zaraďte do fronty, než volajte inline. Ak naraz prevádzate cez jeden kurz veľké skupiny (dátum začiatku kohorty, odomknutie záznamu z webinára), spustite z hooku naplánovanú udalosť cez WP-Cron namiesto synchrónneho volania API:

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

Toto rozloží záťaž a zabráni tomu, aby sa jedna pomalá požiadavka stala problémom študenta. Pre naozaj veľké dávky (celá minulá kohorta presunutá naraz) úplne preskočte cestu cez WordPress hook a použite hromadné udeľovanie cez CSV — nahráte raz a platforma vydávanie stránkuje na strane servera so zabudovaným pozastavením/pokračovaním.

Poznámka k idempotencii

Ak váš LMS niekedy spustí hook dokončenia viac než raz pre toho istého používateľa (bežný hraničný prípad v LearnDash-i pri opakovaní testu, alebo re-synchronizácia v Tutor LMS-e), nechcete udeliť ten istý odznak dvakrát. Najjednoduchšou ochranou je príznak vo WordPress user-meta, ktorý nastavíte hneď po úspešnom volaní:

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

Ak vydávate v skutočne veľkom objeme a chcete, aby sa to riešilo centrálne namiesto po jednotlivých weboch, pozrite si spracovanie udalostí riadené webhookom alebo kompletný API quickstart s tvarmi požiadaviek/odpovedí pre každý endpoint.

Keď tento vzor prerastie jeden kurz

Príklady vyššie predpokladajú jeden odznak na kurz. Hneď ako začnete pracovať so skladateľnými certifikátmi — odznakom pre dráhu, ktorý sa odomkne po niekoľkých odznakoch z kurzov, alebo záverečným odznakom závislým od viacerých predpokladov — presuňte mapovanie „ktorý odznak pre ktoré dokončenie” z post meta do malej vyhľadávacej tabuľky, alebo ho riaďte z automatizácie postavenej na tabuľkovom hárku (Airtable alebo Google Sheets), ktorá spúšťa rovnaké volanie POST /awards. Samotné API volanie sa nemení; mení sa iba to, čo rozhoduje o tom, kedy ho urobiť.

Riešenie problémov s integráciou

Za väčšinu problémov, na ktoré ľudia narazia pri prvom zapájaní tohto riešenia, môže hŕstka príčin:

Hook sa nikdy nespustí. Overte, že zachytávate správnu akciu pre skutočnú verziu svojho pluginu — LearnDash najmä menil názvy hookov pre dokončenie naprieč hlavnými verziami (staršie inštalácie sa niekedy stále spoliehajú na to, že learndash_course_completed sa spustí z inej cesty v kóde než v novších verziách). Pridajte na začiatok svojho callbacku dočasný error_log() a sledujte wp-content/debug.log, kým ako jednorazový používateľ dokončíte testovací kurz.

wp_remote_post() vyprší časový limit. Zdieľané hostingové prostredia niekedy blokujú odchádzajúce HTTPS spojenia na neznáme hosty alebo obmedzujú časový limit požiadavky pod vyššie nastavených 15 sekúnd. Ak volania sústavne vypršia, overte u svojho hostingu, či sú povolené odchádzajúce spojenia na api.badges.ninja, a potvrďte, že vaše PHP rozšírenie curl má aktuálne CA certifikáty — zastaraný balík certifikátov je bežná tichá príčina zlyhania na starších zdieľaných hostingoch.

400 Bad Request. Payloadu chýba povinné pole alebo má nesprávny tvar. POST /awards očakáva badgeId, vnorený objekt recipient s name a email a časovú značku issuedOn — pomocná funkcia vyššie presne toto odosiela. Najčastejším zádrhelom je meno príjemcu: musí mať aspoň 5 znakov, takže zobrazované meno vo WordPresse ako „Jo” je odmietnuté. Ak je zobrazované meno príliš krátke, použite ako náhradu celé meno účtu (alebo časť e-mailu pred zavináčom).

401 Unauthorized. Konštanta s API kľúčom sa nenačítava, alebo bol kľúč po nastavení konštanty znovu vygenerovaný. Kľúče sa zobrazia iba raz pri vytvorení a nedajú sa znovu získať — ak ste stratili prehľad o tom, ktorý kľúč je aktívny, radšej starý vymažte a vydajte nový, namiesto hádania.

Odznak bol udelený, ale s nesprávnym dizajnom. Toto je takmer vždy zastaraná hodnota post-meta badges_ninja_badge_id zostávajúca z testovania. Keďže mapovanie žije na zázname kurzu, ľahko sa zabudne, že ste ho zmenili po duplikovaní kurzu pre novú kohortu — oplatí sa rýchla kontrola vždy, keď kurz klonujete.

Duplicitné udelenia pre tú istú osobu. Riešené vyššie pomocou ochrany cez user-meta, ale stojí za zopakovanie: nie je zaručené, že sa hooky dokončenia v LMS spustia presne raz. Považujte „už udelené” za bežný prípad, ktorý treba kontrolovať, nie za hraničný prípad, ktorý sa dá ignorovať.

Často kladené otázky

Funguje to s balíkmi kurzov vo WooCommerce? Áno — ak má nákup balíka spustiť odznak nezávisle od dokončenia kurzu (napr. odznak „certifikovaný člen” pre každého, kto kúpi konkrétny balík), zachyťte namiesto akcie pre dokončenie LMS woocommerce_order_status_completed a ID odznaku vyhľadajte z meta produktu, nie kurzu.

Môžu príjemcovia získať odznak bez WordPress účtu? Áno, a o to práve ide. Udelenie je viazané na ich e-mailovú adresu v Badges Ninja, nie na záznam WordPress používateľa. Ak váš web umožňuje nákup ako hosť alebo anonymné dokončenie testu, len sa uistite, že zachytávate skutočnú e-mailovú adresu, ktorú odovzdáte do badges_ninja_issue_award().

Čo ak chcem udelenia pred odoslaním skontrolovať? Nespúšťajte volanie priamo z hooku dokončenia. Namiesto toho zapíšte čakajúce udelenie (používateľ, kurz, časová značka) do vlastnej tabuľky alebo typu záznamu a vydajte ho z naplánovanej úlohy alebo administrátorského tlačidla „Approve & Award”, ktoré na požiadanie zavolá tú istú pomocnú funkciu.

Potrebujem samostatný odznak pre každý kurz, alebo môže jeden odznak pokrývať viacero? Funguje oboje. Niektorí vydavatelia vytvárajú jeden odznak na kurz kvôli väčšej granularite; iní vytvoria jediný odznak „dokončenie programu” a udelia ho až po dokončení všetkých požadovaných kurzov, pričom v hooku pred volaním API skontrolujú splnenie predpokladov.

---

Ste pripravení vydať svoj prvý overiteľný certifikát? Začnite zadarmo na badges.ninja — vizuálny dizajnér, verejná stránka na overenie, PDF certifikát, výstup Open Badge v2.0. Kreditná karta nie je potrebná.