Open Badges išdavimas iš WordPress (be sudėtingo papildinio)

Jei valdote kursus WordPress platformoje, jau žinote, kaip viskas vyksta: kažkas užbaigia modulį LearnDash, LifterLMS ar Tutor LMS sistemoje, MVS pažymi jį kaip „baigtą”, ir tada… nieko patikrinamo neįvyksta. Galbūt išsiunčiate PDF el. paštu. Galbūt įsidiegiate atskirą WordPress ženklelių papildinį, kuris prideda savo duomenų bazės lenteles, savo vaizdų biblioteką ir savo supratimą, kas yra „ženklelis” — toks, kurio niekas už jūsų svetainės ribų negali patikrinti.

Yra paprastesnis kelias. WordPress kursų papildiniai jau iškviečia veiksmo kablį (angl. hook) tą akimirką, kai kažkas užbaigia kursą. Galite pagauti šį kablį ir atlikti vieną HTTP užklausą į Badges Ninja API. Jokio papildomo papildinio, jokio papildomo prieglobos, jokio nuosavo ženklelio formato — tik standartus atitinkanti Open Badge v2.0 kredencialas, kurį jūsų gavėjas gali patikrinti bet kur, pridėti prie LinkedIn ir atsisiųsti kaip PDF.

Šiame įraše kartą aprašomas šis modelis, o tada parodomas konkretus kablys, skirtas LearnDash, LifterLMS ir Tutor LMS sistemoms.

Kodėl tiesiog nenaudoti WordPress ženklelių papildinio?

Specializuoti WordPress ženklelių papildiniai iš tiesų sprendžia siauresnę problemą, nei atrodo iš pirmo žvilgsnio. Jie gerai atlieka vieną dalyką — atvaizduoja paveikslėlį jūsų svetainės „mano pasiekimai” puslapyje. Tačiau paprastai jie kur kas silpnesni tose srityse, kurios iš tikrųjų svarbios kredencialui:

Perkeliamumas. Ženklelis, kuris egzistuoja tik kaip trumpasis kodas (shortcode) jūsų WordPress svetainėje, nėra kredencialas — tai puošmena. Vos tik gavėjas pakeičia darbą, pakeičia el. pašto dėžutę ar jūsų svetainė nustoja veikti, kartu dingsta ir „įrodymas”.
Patikrinimas. Bet kas turėtų galėti patikrinti, ar kredencialas tikras, neprisijungdamas prie jūsų WordPress administravimo skydelio. Open Badge v2.0 standartas iš esmės suteikia viešą patikrinimo URL ir mašinai skaitomą JSON-LD formatą.
Priežiūros apimtis. Kiekvienas WordPress papildinys yra dar vienas dalykas, kurį reikia atnaujinti, dar viena duomenų bazės lentelė, kurią reikia rezervuoti, dar vienas galimas gedimo taškas atnaujinant branduolį.

Išorinio API iškvietimas užbaigus kursą apeina visas tris problemas. WordPress lieka atsakingas už tai, ką jis geriausiai daro — turinio pateikimą ir pažangos stebėjimą, o pats kredencialas gyvena sistemoje, sukurtoje specialiai jam išduoti, patikrinti ir juo dalintis.

Modelis: vienas kablys, viena HTTP užklausa

Kiekvienas didesnis WordPress MVS papildinys iškviečia veiksmą, kai vartotojas užbaigia kursą. Integracija visada susideda iš tų pačių trijų žingsnių:

Prisijunkite prie užbaigimo veiksmo savo konkrečioje MVS sistemoje.
Suraskite (arba sukurkite) gavėjo tapatybę — paprastai tiesiog jo WordPress paskyros el. paštą ir rodomą vardą.
Iškvieskite POST /awards Badges Ninja API naudodami wp_remote_post(), perduodami ženklelio ID ir gavėjo duomenis.

Pirmiausia jums reikės API rakto. Sugeneruokite jį savo valdymo skyde skiltyje API Keys — visą procesą rasite API raktų vadove. Raktai parodomi tik vieną kartą sukūrimo metu, todėl saugokite jį wp-config.php faile kaip konstantą, o ne duomenų bazėje:

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

Naujai sukurtas raktas parodomas vieną kartą

Šį raktą laikykite serverio pusėje. Viskas šiame vadove vyksta PHP kalba jūsų WordPress serveryje — wp_remote_post() yra serverio pusės užklausa, o wp-config.php niekada nesiunčiamas į naršyklę. Būtent to ir reikia: raktas keliauja iš serverio į serverį per HTTPS, ir nė vienas svetainės lankytojas negali jo perskaityti. Niekada neperkelkite šio iškvietimo į kliento pusės JavaScript kodą — fetch() užklausa iš naršyklės su įterptu raktu atskleistų jį bet kam per naršyklės kūrėjo įrankius. Verta laikytis dviejų įpročių: įsitikinkite, kad jūsų prieglobos paslaugų teikėjas pateikia wp-config.php kaip vykdomą PHP kodą (niekada kaip paprastą tekstą, ir nepalikite wp-config.php.bak kopijos svetainės šakniniame kataloge), bei sukurkite atskirą API raktą šiai integracijai, kad prireikus galėtumėte jį atšaukti nepriklausomai, jei jis kada nors būtų pažeistas — nesugadindami kitų savo įrankių.

Bendra pagalbinė funkcija leidžia kiekvieną MVS kablį palikti trumpą:

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

Gavėjo el. paštas serverio pusėje sumaišomas SHA-256 algoritmu, kai tik pasiekia Badges Ninja, o grąžinamame atsakyme yra apdovanojimo patikrinimo URL — tai naudinga, jei norite iškart WordPress parodyti nuorodą „peržiūrėti savo kredencialą”, kai iškvietimas pavyksta.

LearnDash

LearnDash iškviečia learndash_course_completed su vienu masyvo argumentu, kuriame yra user ir 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 );
} );

Ženklelio ID saugojimas kaip kurso metaduomenų (o ne kaip vienos bendros BADGES_NINJA_BADGE_ID konstantos) yra teisingas sprendimas, kai turite daugiau nei vieną kursą — kiekvienas kursas atitinka savo ženklelio dizainą.

LifterLMS

LifterLMS iškviečia lifterlms_course_completed su $user_id ir $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 iškviečia tutor_course_complete_after su kurso ID, o esamą vartotoją gaunate iš sesijos:

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

Jei jūsų Tutor LMS konfigūracija iškviečia užbaigimą iš fono proceso (pvz., per automatinį testo vertinimą), pakeiskite get_current_user_id() vartotojo ID, kurį pateikia jūsų konkretus kablys — vieną kartą diegimo metu patikrinkite duomenis su error_log( print_r( func_get_args(), true ) ), kad įsitikintumėte argumentais.

Ženklelio sukūrimas prieš prijungiant kablį

Prieš tai suveikiant, jums reikia ženklelio, kurį galėtumėte įteikti. Vizualinis dizaino įrankis tai apima be reikalo samdyti dizainerį — 80+ formų šablonų, pasirinktinos spalvos, ikonų biblioteka ir logotipo įkėlimas, viskas su prisitraukimu prie tinklelio. Jei dizaino įrankis jums naujas, Pirmojo patikrinamo skaitmeninio sertifikato projektavimas žingsnis po žingsnio parodo, kaip pasirinkti šabloną ir sukurti kažką, kuo gavėjai tikrai norės dalintis.

Kai ženklelis jau sukurtas, gaukite jo ID iš valdymo skydo (arba per GET /badges) ir įrašykite jį į savo kurso pasirinktinį lauką.

Ką gavėjas iš tikrųjų gauna

Būtent šios dalies namudinis WordPress ženklelių papildinys negali atkartoti. Kai POST /awards pavyksta, gavėjas gauna:

Unikalų patikrinimo URL, kurį gali atverti bet kas — neprisijungiant prie WordPress — rodantį, kad kredencialas tikras, kas jį išdavė ir kada.
Automatiškai sugeneruotą QR kodą ir A4 formato PDF sertifikatą.
Mygtuką Pridėti į LinkedIn profilį, jei jūsų išdavėjas turi nustatytą LinkedIn organizacijos ID — vienkartinę sąranką rasite LinkedIn mygtuko „Pridėti į profilį” pridėjimas.
Prieigą prie savo gavėjo portalo, pasiekiamo adresu badges.ninja/me, prisijungiant per magic-link nuorodą — jokio slaptažodžio, kurį reikėtų pamiršti, jokios atskiros paskyros, kurią reikėtų valdyti jūsų WordPress svetainėje.
Standartus atitinkantį Open Badge v2.0 JSON-LD formatą, todėl jį gali patvirtinti bet kuris OB standartą palaikantis tikrintojas (ne tik Badges Ninja).

Nieko iš to nėra WordPress užduotis kurti, ir nieko iš to neturėtų egzistuoti vien tik jūsų WordPress duomenų bazėje.

Sklandus klaidų valdymas

Kurso užbaigimo kabliai suveikia realaus puslapio užklausos metu, todėl lėtas ar nepavykęs API iškvietimas neturėtų blokuoti besimokančiojo „sveikinimo” ekrano. Štai du praktiniai patobulinimai, kai peržengiate koncepcijos įrodymo etapą:

Neleiskite nepavykusiam apdovanojimui blokuoti sąsajos. Aukščiau pateikta pagalbinė funkcija jau registruoja klaidą žurnale ir grąžina false, o ne meta išimtį — LearnDash, LifterLMS ir Tutor toliau tęsia įprastą užbaigimo eigą, nepriklausomai nuo to, ką grąžina badges_ninja_issue_award().

Dideliu mastu naudokite eilę, o ne tiesioginį iškvietimą. Jei per vieną kursą vienu metu praleidžiate dideles grupes (kohortos pradžios data, internetinio seminaro įrašo atrakinimas), iš kablio suaktyvinkite suplanuotą WP-Cron įvykį, o ne kvieskite API sinchroniškai:

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

Tai paskirsto apkrovą ir neleidžia vienai lėtai užklausai tapti besimokančiojo problema. Tikrai dideliems paketams (visa praeities kohorta, perkelta vienu kartu) visiškai praleiskite WordPress kablio kelią ir naudokite masinį apdovanojimų išdavimą per CSV — įkelkite vieną kartą, o platforma serverio pusėje puslapiuoja išdavimą su įmontuota pauzės / tęsimo funkcija.

Pastaba apie idempotentiškumą

Jei jūsų MVS kada nors iškviečia užbaigimo kablį tam pačiam vartotojui daugiau nei kartą (dažnas LearnDash ribinis atvejis su pakartotiniais testo bandymais arba Tutor LMS pakartotine sinchronizacija), nenorėsite du kartus įteikti to paties ženklelio. Paprasčiausia apsauga — WordPress vartotojo metaduomenų žymė, kurią nustatote iškart po sėkmingo iškvietimo:

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

Jei išduodate tikrai dideliu mastu ir norite, kad tai būtų valdoma centralizuotai, o ne kiekvienoje svetainėje atskirai, žiūrėkite įvykių valdymą per webhook’us arba pilną API greitosios pradžios vadovą, kuriame aprašomos užklausų / atsakymų struktūros visiems galiniams taškams.

Kai šis modelis peržengia vieno kurso ribas

Aukščiau pateikti pavyzdžiai daro prielaidą, kad kiekvienam kursui tenka po vieną ženklelį. Kai pradedate naudoti sukraunamus (angl. stackable) kredencialus — trajektorijos ženklelį, kuris atrakinamas po kelių kursų ženklelių, arba baigiamąjį ženklelį, priklausantį nuo kelių išankstinių sąlygų — perkelkite atitikmenį „kuris ženklelis kuriam užbaigimui” iš įrašo metaduomenų į nedidelę paieškos lentelę arba valdykite jį per skaičiuoklės pagrindu veikiančią automatizaciją (Airtable ar Google Sheets), kuri iškviečia tą patį POST /awards užklausą. Pats API iškvietimas nesikeičia — keičiasi tik tai, kas nusprendžia, kada jį atlikti.

Integracijos trikčių šalinimas

Kelios problemos sudaro didžiąją dalį sunkumų, su kuriais žmonės susiduria diegdami šią integraciją pirmą kartą:

Kablys niekada nesuveikia. Įsitikinkite, kad prisijungiate prie teisingo veiksmo, atitinkančio faktinę jūsų papildinio versiją — ypač LearnDash tarp didesnių leidimų keitė užbaigimo kablio pavadinimus (senesnėse diegimo versijose kartais vis dar learndash_course_completed suveikia iš kitokio kodo kelio nei naujesnėse). Laikinai įtraukite error_log() savo atgalinio iškvietimo pradžioje ir stebėkite wp-content/debug.log, kol užbaigiate testinį kursą su vienkartiniu vartotoju.

wp_remote_post() baigiasi pagal laiko limitą. Bendro naudojimo prieglobos aplinkos kartais blokuoja išeinančias HTTPS jungtis į nepažįstamus serverius arba apriboja užklausų laiko limitą žemiau aukščiau nustatytų 15 sekundžių. Jei iškvietimai nuolat baigiasi pagal laiko limitą, pasiteiraukite savo prieglobos paslaugų teikėjo, ar leidžiamos išeinančios jungtys į api.badges.ninja, ir įsitikinkite, kad jūsų PHP curl plėtinys turi naujausius CA sertifikatus — pasenęs sertifikatų paketas yra dažna tyli gedimo priežastis senesnėse bendro naudojimo prieglobos sistemose.

400 Bad Request. Duomenų pakete trūksta privalomo lauko arba jo struktūra neteisinga. POST /awards tikisi badgeId, įdėto recipient objekto su name ir email, bei issuedOn laiko žymos — būtent tai ir siunčia aukščiau pateikta pagalbinė funkcija. Dažniausia klaida — gavėjo vardas: jis turi būti bent 5 simbolių ilgio, todėl toks WordPress rodomas vardas kaip „Jo” atmetamas. Kai rodomas vardas per trumpas, naudokite paskyros pilną vardą (arba el. pašto dalį iki @) kaip atsarginį variantą.

401 Unauthorized. API rakto konstanta neįkeliama arba raktas buvo sugeneruotas iš naujo po to, kai konstanta jau buvo nustatyta. Raktai parodomi tik vieną kartą sukūrimo metu ir vėliau jų atgauti negalima — jei nebeatsimenate, kuris raktas šiuo metu galioja, ištrinkite pasenusį ir sukurkite naują, o ne spėliokite.

Ženklelis išduotas, bet su neteisingu ženklelio dizainu. Tai beveik visada pasenusi badges_ninja_badge_id įrašo metaduomenų reikšmė, likusi po testavimo. Kadangi atitikmuo saugomas kurso įraše, lengva pamiršti, kad jį pakeitėte, pasidauginę kursą naujai kohortai — verta greitai patikrinti kiekvieną kartą, kai klonuojate kursą.

Dubliuoti apdovanojimai tam pačiam žmogui. Tai aptarta aukščiau su vartotojo metaduomenų apsauga, bet verta pakartoti: negarantuojama, kad MVS užbaigimo kabliai suveiks lygiai vieną kartą. Traktuokite „jau apdovanota” kaip įprastą atvejį, kurį reikia tikrinti, o ne kaip ribinį atvejį, kurį galima ignoruoti.

Dažnai užduodami klausimai

Ar tai veikia su WooCommerce kursų rinkiniais? Taip — jei rinkinio pirkimas turėtų suaktyvinti ženklelį nepriklausomai nuo kurso užbaigimo (pvz., „sertifikuoto nario” ženklelį visiems, kurie perka konkretų rinkinį), prisijunkite prie woocommerce_order_status_completed veiksmo, o ne prie MVS užbaigimo veiksmo, ir ženklelio ID ieškokite produkto metaduomenyse, o ne kurse.

Ar gavėjai gali gauti ženklelį neturėdami WordPress paskyros? Taip, ir būtent tai yra esmė. Apdovanojimas Badges Ninja sistemoje susiejamas su jų el. pašto adresu, o ne su WordPress vartotojo įrašu. Jei jūsų svetainė leidžia atsiskaityti kaip svečiui arba anonimiškai užbaigti testą, tiesiog įsitikinkite, kad fiksuojate tikrą el. pašto adresą, kurį perduosite badges_ninja_issue_award() funkcijai.

O jei noriu peržiūrėti apdovanojimus prieš jiems išsiunčiant? Nekvieskite užklausos tiesiai iš užbaigimo kablio. Vietoj to, laukiantį apdovanojimą (vartotoją, kursą, laiko žymą) įrašykite į pasirinktinę lentelę arba įrašo tipą ir išduokite jį iš suplanuotos užduoties arba administravimo mygtuko „Patvirtinti ir apdovanoti”, kuris pagal poreikį iškviečia tą pačią pagalbinę funkciją.

Ar man reikia atskiro ženklelio kiekvienam kursui, ar vienas ženklelis gali apimti kelis? Tinka abu variantai. Vieni išdavėjai kuria po vieną ženklelį kiekvienam kursui, siekdami didesnio detalumo; kiti sukuria vieną „programos užbaigimo” ženklelį ir jį įteikia tik užbaigus visus privalomus kursus, patikrinę išankstinių sąlygų įvykdymą kablio viduje prieš iškviečiant API.

Pasiruošę išduoti savo pirmąjį patikrinamą kredencialą? Pradėkite nemokamai svetainėje badges.ninja — vizualinis dizaino įrankis, vieša patikrinimo svetainė, PDF sertifikatas, Open Badge v2.0 formatas. Kredito kortelė nereikalinga.