Open Badges izsniegšana no WordPress (bez apjomīga spraudņa)

Ja jūs vadāt kursus WordPress vidē, jūs jau zināt, kā tas notiek: kāds pabeidz moduli LearnDash, LifterLMS vai Tutor LMS platformā, LMS atzīmē viņu kā “pabeigušu”, un tad… nekas pārbaudāms nenotiek. Varbūt jūs nosūtāt PDF pa e-pastu. Varbūt instalējat īpašu WordPress nozīmju spraudni, kas pievieno savas datubāzes tabulas, savu attēlu bibliotēku un savu izpratni par to, kas ir “nozīme” — tādu, ko neviens ārpus jūsu vietnes nevar pārbaudīt.

Ir vienkāršāks ceļš. WordPress kursu spraudņi jau izsauc darbības āķi (action hook) tieši tajā brīdī, kad kāds pabeidz kursu. Jūs varat noķert šo āķi un veikt vienu HTTP izsaukumu uz Badges Ninja API. Nav vajadzīgs papildu spraudnis, papildu hostings vai patentēts nozīmju formāts — tikai standartiem atbilstoša Open Badge v2.0 apliecība, ko jūsu saņēmējs var pārbaudīt jebkur, pievienot LinkedIn profilam un lejupielādēt kā PDF.

Šajā rakstā vispirms tiek izklāstīts vispārīgais modelis, tad parādīts konkrētais āķis LearnDash, LifterLMS un Tutor LMS platformām.

Kāpēc gan neizmantot vienkārši WordPress nozīmju spraudni?

Īpaši WordPress nozīmju spraudņi atrisina šaurāku problēmu, nekā šķiet no pirmā acu uzmetiena. Tie labi prot attēlot attēlu jūsu vietnes lapā “mani sasniegumi”. Parasti tie ir daudz vājāki tajās lietās, kas patiesībā ir svarīgas apliecībai:

• Pārnesamība. Nozīme, kas eksistē tikai kā īsais kods (shortcode) jūsu WordPress vietnē, nav apliecība — tā ir dekorācija. Brīdī, kad saņēmējs maina darbu, maina savu e-pasta kastīti vai jūsu vietne pārstāj darboties, kopā ar to pazūd arī “pierādījums”.
• Verifikācija. Ikvienam vajadzētu būt iespējai pārbaudīt, ka apliecība ir īsta, nepiesakoties jūsu WordPress administrēšanas panelī. Open Badge v2.0 pēc uzbūves nodrošina publisku verifikācijas URL un mašīnlasāmu JSON-LD.
• Uzturēšanas apjoms. Katrs WordPress spraudnis ir vēl viena lieta, kas jālabo, vēl viena datubāzes tabula, kas jārezervē, vēl viens kļūmes punkts kodola atjaunināšanas laikā.

Ārējā API izsaukšana kursa pabeigšanas brīdī novērš visas trīs problēmas. WordPress paliek atbildīgs par to, kas tam padodas vislabāk — satura piegādi un progresa izsekošanu —, savukārt pati apliecība dzīvo sistēmā, kas īpaši izveidota tās izsniegšanai, verifikācijai un koplietošanai.

Modelis: viens āķis, viens HTTP izsaukums

Katrs lielākais WordPress LMS spraudnis izsauc darbību, kad lietotājs pabeidz kursu. Integrācija vienmēr sastāv no tiem pašiem trim soļiem:

1. Piekabinieties konkrētā LMS pabeigšanas darbībai.
2. Atrodiet (vai izveidojiet) saņēmēja identitāti — parasti vienkārši viņa WordPress konta e-pastu un attēlojamo vārdu.
3. Izsauciet POST /awards uz Badges Ninja API, izmantojot wp_remote_post(), nododot nozīmes ID un saņēmēja datus.

Vispirms jums būs nepieciešama API atslēga. Izveidojiet to savā vadības panelī sadaļā API Keys — pilnu izklāstu skatiet API atslēgu ceļvedī. Atslēgas tiek parādītas tikai vienu reizi izveides brīdī, tāpēc saglabājiet to kā konstanti failā wp-config.php, nevis datubāzē:

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

Turiet šo atslēgu servera pusē. Viss šajā ceļvedī darbojas kā PHP jūsu WordPress serverī — wp_remote_post() ir servera puses izsaukums, un wp-config.php nekad netiek nosūtīts pārlūkprogrammai. Tieši to jūs vēlaties: atslēga ceļo no servera uz serveri, izmantojot HTTPS, un neviens vietnes apmeklētājs to nevar nolasīt. Nekad nepārnesiet šo izsaukumu uz klienta puses JavaScript — fetch() izsaukums no pārlūkprogrammas ar atslēgu, kas iekļauta tieši kodā, padarītu to redzamu ikvienam, izmantojot pārlūkprogrammas izstrādātāja rīkus. Divi ieradumi ir vērts saglabāt: pārliecinieties, ka jūsu hostings apkalpo wp-config.php kā izpildītu PHP (nekad kā vienkāršu tekstu) un neatstāj wp-config.php.bak kopiju tīmekļa saknes mapē, un izveidojiet atsevišķu API atslēgu šai integrācijai, lai varētu to atsaukt neatkarīgi, ja tā kādreiz tiek kompromitēta — nesabojājot pārējos jūsu rīkus.

Kopīga palīgfunkcija katru LMS āķi padara vienkāršu:

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

Saņēmēja e-pasts serveru pusē tiek jaucts ar SHA-256, tiklīdz tas sasniedz Badges Ninja, un atgrieztais rezultāts ietver piešķīruma verifikācijas URL — noderīgi, ja vēlaties WordPress vidē uzreiz pēc veiksmīga izsaukuma parādīt saiti “skatīt savu apliecību”.

LearnDash

LearnDash izsauc learndash_course_completed ar vienu masīva argumentu, kas satur user un 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 );
} );

Nozīmes ID saglabāšana kā kursa metadati (nevis kā viena globāla konstante BADGES_NINJA_BADGE_ID) ir pareizais risinājums, tiklīdz jums ir vairāk nekā viens kurss — katrs kurss atbilst savam nozīmes dizainam.

LifterLMS

LifterLMS izsauc lifterlms_course_completed ar $user_id un $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 izsauc tutor_course_complete_after ar kursa ID, un pašreizējo lietotāju jūs iegūstat no sesijas:

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

Ja jūsu Tutor LMS iestatījumi izsauc pabeigšanu no fona procesa (piemēram, izmantojot testa automātisko vērtēšanu), aizstājiet get_current_user_id() ar lietotāja ID, ko nodrošina jūsu konkrētais āķis — pārbaudiet slodzi vienu reizi iestatīšanas laikā, izmantojot error_log( print_r( func_get_args(), true ) ), lai apstiprinātu argumentus.

Nozīmes izveide pirms āķa pieslēgšanas

Pirms kaut kas no tā tiek izsaukts, jums ir nepieciešama nozīme, ko piešķirt. Vizuālais dizaineris to aptver bez nepieciešamības pēc dizainera komandā — vairāk nekā 80 formu veidnes, pielāgotas krāsas, ikonu bibliotēka un logotipa augšupielāde, viss ar pieķeršanos režģim. Ja esat jauns dizainera lietotājs, jūsu pirmās pārbaudāmās digitālās apliecības izveide izklāsta veidnes izvēli un kaut kā tāda piegādi, ko saņēmēji patiešām vēlēsies koplietot.

Kad nozīme ir izveidota, iegūstiet tās ID no vadības paneļa (vai izmantojot GET /badges) un ievietojiet to sava kursa pielāgotajā laukā.

Ko saņēmējs patiesībā iegūst

Tā ir daļa, ko mājās veidots WordPress nozīmju spraudnis nespēj atkārtot. Kad POST /awards izdodas, saņēmējs iegūst:

• Unikālu verifikācijas URL, ko var atvērt ikviens — bez nepieciešamības pieteikties WordPress —, kas parāda, ka apliecība ir īsta, kas to izsniedza un kad.
• QR kodu un A4 formāta PDF sertifikātu, kas tiek ģenerēts automātiski.
• Pogu Pievienot LinkedIn profilam, ja jūsu izsniedzējam ir iestatīts LinkedIn organizācijas ID — skatiet LinkedIn “pievienot profilam” pogas pievienošana vienreizējai iestatīšanai.
• Piekļuvi savam saņēmēja portālam vietnē badges.ninja/me, izmantojot pieteikšanos ar burvju saiti (magic link) — nav paroles, ko aizmirst, un nav atsevišķa konta, kas jāpārvalda jūsu WordPress vietnē.
• Standartiem atbilstošu Open Badge v2.0 JSON-LD, ko var validēt jebkurš OB pratīgs verificētājs (ne tikai Badges Ninja).

Nekas no tā nav WordPress uzdevums, un nekam no tā nevajadzētu dzīvot tikai jūsu WordPress datubāzē.

Kļūdu elegants risinājums

Kursa pabeigšanas āķi tiek izsaukti dzīvā lapas pieprasījuma laikā, un lēns vai neveiksmīgs API izsaukums nedrīkstētu bloķēt audzēkņa “apsveicam” ekrānu. Divi praktiski pielāgojumi, tiklīdz pārsniedzat koncepcijas pierādījuma posmu:

Neļaujiet neveiksmīgam piešķīrumam bloķēt saskarni. Iepriekš minētā palīgfunkcija jau reģistrē kļūdu un atgriež false, nevis izmet izņēmumu — LearnDash, LifterLMS un Tutor visi turpina savu parasto pabeigšanas plūsmu neatkarīgi no tā, ko atgriež badges_ninja_issue_award().

Lielākā mērogā ievietojiet to rindā, nevis izsauciet iekļauti. Ja jūs vienlaikus vadāt lielas grupas cauri vienam kursam (kohortas sākuma datums, tīmekļa semināra ieraksta atbloķēšana), izsauciet no āķa plānotu WP-Cron notikumu, nevis sinhroni izsauciet 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 );

Tas izkliedē slodzi un neļauj vienam lēnam pieprasījumam kļūt par audzēkņa problēmu. Patiesi lielām partijām (visa iepriekšējā kohorta, migrēta vienā reizē) pilnībā izlaidiet WordPress āķa ceļu un izmantojiet masveida piešķiršanu, izmantojot CSV — augšupielādējiet vienreiz, un platforma izsniegšanu servera pusē lappuse pa lappusei ar iebūvētu pauzēšanu un atsākšanu.

Piezīme par idempotenci

Ja jūsu LMS jebkad izsauc savu pabeigšanas āķi vairāk nekā vienu reizi tam pašam lietotājam (izplatīts LearnDash robežgadījums ar testu atkārtotu kārtošanu vai Tutor LMS atkārtotu sinhronizāciju), jūs nevēlaties piešķirt to pašu nozīmi divreiz. Vienkāršākā aizsardzība ir WordPress lietotāja metadatu karogs, ko iestatāt uzreiz pēc veiksmīga izsaukuma:

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

Ja izsniedzat patiesi lielos apjomos un vēlaties to pārvaldīt centralizēti, nevis katrā vietnē atsevišķi, apskatiet ar tīmekļa āķi (webhook) vadītu notikumu apstrādi vai pilnu API ātro sākumu, lai iegūtu pieprasījuma un atbildes formas katram galapunktam.

Kad šis modelis pārsniedz viena kursa robežas

Iepriekšējie piemēri pieņem vienu nozīmi vienam kursam. Tiklīdz jūs sākat izmantot sakrājamas apliecības — celiņa nozīmi, kas atbloķējas pēc vairākām kursu nozīmēm, vai noslēguma nozīmi, kas ir atkarīga no vairākiem priekšnosacījumiem —, pārvietojiet kartējumu “kura nozīme kurai pabeigšanai” no ieraksta metadatiem uz nelielu uzmeklēšanas tabulu vai vadiet to no izklājlapā balstītas automatizācijas (Airtable vai Google Sheets), kas izsauc to pašu POST /awards izsaukumu. Pats API izsaukums nemainās — mainās tikai tas, kas nosaka, kad to veikt.

Integrācijas problēmu novēršana

Neliela problēmu kopa veido lielāko daļu grūtību, ar kurām cilvēki saskaras, pirmo reizi pieslēdzot šo integrāciju:

Āķis nekad neizsaucas. Pārliecinieties, ka piekabināties pareizajai darbībai savai spraudņa faktiskajai versijai — jo īpaši LearnDash ir mainījis pabeigšanas āķu nosaukumus starp lielākiem izlaidumiem (vecākas instalācijas dažkārt joprojām paļaujas uz to, ka learndash_course_completed izsaucas no cita koda ceļa nekā jaunākajās). Pievienojiet pagaidu error_log() sava atzvana sākumā un vērojiet wp-content/debug.log, kamēr pabeidzat testa kursu kā vienreiz lietojamu lietotāju.

wp_remote_post() iestājas noildze. Koplietotas hostinga vides dažreiz bloķē izejošo HTTPS uz nepazīstamiem serveriem vai ierobežo pieprasījumu noildzi zem iepriekš minētajām 15 sekundēm. Ja izsaukumi konsekventi sasniedz noildzi, pārbaudiet ar savu hostingu, vai izejošie savienojumi ar api.badges.ninja ir atļauti, un pārliecinieties, ka jūsu PHP curl paplašinājumam ir aktuāli CA sertifikāti — novecojis sertifikātu komplekts ir izplatīta klusa kļūme vecākos koplietotas hostinga stekos.

400 Bad Request. Datu kopumā trūkst obligāta lauka vai tam ir nepareiza forma. POST /awards sagaida badgeId, iegultu recipient objektu ar name un email, kā arī issuedOn laika zīmogu — iepriekš minētā palīgfunkcija nosūta tieši to. Visbiežākais klupšanas akmens ir saņēmēja vārds: tam jābūt vismaz 5 rakstzīmju garam, tāpēc WordPress attēlojamais vārds, piemēram, “Jo”, tiek noraidīts. Ja attēlojamais vārds ir pārāk īss, izmantojiet konta pilno vārdu (vai e-pasta lokālo daļu).

401 Unauthorized. API atslēgas konstante netiek ielādēta, vai tā tika atkārtoti ģenerēta pēc konstantes iestatīšanas. Atslēgas tiek parādītas tikai vienu reizi izveides brīdī, un tās vēlāk nevar atkārtoti iegūt — ja esat pazaudējis pārskatu par to, kura atslēga ir aktīva, dzēsiet novecojušo un izsniedziet jaunu, nevis minat.

Nozīme izsniegta, bet ar nepareizu nozīmes dizainu. Tas gandrīz vienmēr ir novecojis badges_ninja_badge_id ieraksta metadatu lauks, kas palicis pāri no testēšanas. Tā kā kartējums dzīvo kursa ierakstā, ir viegli aizmirst, ka to mainījāt pēc kursa dublēšanas jaunai kohortai — vērts ātri pārbaudīt ikreiz, kad klonējat kursu.

Dublēti piešķīrumi vienai un tai pašai personai. Tas aplūkots iepriekš ar lietotāja metadatu aizsardzību, taču vērts atkārtot: LMS pabeigšanas āķi nav garantēti izsaukti tieši vienu reizi. Attieciet “jau piešķirts” kā parastu gadījumu, kas jāpārbauda, nevis kā robežgadījumu, ko var ignorēt.

Biežāk uzdotie jautājumi

Vai tas darbojas ar WooCommerce kursu paketēm? Jā — ja paketes pirkumam vajadzētu izraisīt nozīmi neatkarīgi no kursa pabeigšanas (piemēram, “sertificēta locekļa” nozīmi ikvienam, kurš iegādājas konkrētu paketi), piekabinieties woocommerce_order_status_completed vietā LMS pabeigšanas darbības un meklējiet nozīmes ID produkta metadatos, nevis kursā.

Vai saņēmēji var iegūt nozīmi bez WordPress konta? Jā, un tieši tas ir mērķis. Piešķīrums ir piesaistīts viņu e-pasta adresei Badges Ninja, nevis WordPress lietotāja ierakstam. Ja jūsu vietne pieļauj pirkšanu kā viesim vai anonīmu testa pabeigšanu, vienkārši pārliecinieties, ka tverat īstu e-pasta adresi, ko nododat funkcijai badges_ninja_issue_award().

Ko darīt, ja vēlos pārskatīt piešķīrumus, pirms tie tiek nosūtīti? Izlaidiet izsaukuma tiešu izsaukšanu no pabeigšanas āķa. Tā vietā rakstiet gaidošo piešķīrumu (lietotājs, kurss, laika zīmogs) pielāgotā tabulā vai ieraksta tipā un izsniedziet to no plānota uzdevuma vai administratora pogas “Apstiprināt un piešķirt”, kas pēc pieprasījuma izsauc to pašu palīgfunkciju.

Vai man ir nepieciešama atsevišķa nozīme katram kursam, vai viena nozīme var aptvert vairākus? Abi risinājumi darbojas. Daži izsniedzēji izveido vienu nozīmi katram kursam detalizācijas dēļ; citi izveido vienu “programmas pabeigšanas” nozīmi un piešķir to tikai tad, kad ir pabeigti visi nepieciešamie kursi, pārbaudot priekšnosacījumu izpildi āķa iekšienē pirms API izsaukšanas.

---

Gatavs izsniegt savu pirmo pārbaudāmo apliecību? Sāciet bez maksas vietnē badges.ninja — vizuālais dizaineris, publiska verifikācijas lapa, PDF sertifikāts, Open Badge v2.0 izvade. Kredītkarte nav nepieciešama.