Green Bridge don masu haɓaka manhaja

Yadda komai ke haɗuwa

Ƙirƙiri maɓallai kuma ku ƙara shafukanku a cikin console.
Don jarrabawar gwaji, liƙa guntun lambar a shafinku.
Don gwajinku, sabar ɗinku tana fara gwaji kuma tana karɓar adireshin farawa.
Shafinku yana buɗe shi, ɗan takara yana yin gwajin, sakamakon kuma yana isowa gare ku ta webhook ko API.

Maɓallai

pk_test_ pk_live_: Maɓallan da za a iya bayyanawa suna shiga shafukan yanar gizonku. Jarrabawar gwaji kaɗai suke buɗewa, a shafukan da kuka lissafa.
sk_test_ sk_live_: Maɓallan sabar suna aiki a madadin ƙungiyarku. Ajiye su a sabar ɗinku, kada ku aika su zuwa burauza.

Maɓallan gwaji suna aiki nan take kuma ba a ƙirga su a tsarinku. Maɓallan live suna buƙatar a amince da asusunku.

Jarrabawar gwaji

Ƙara rubutun sau ɗaya, sannan ku sanya jarrabawa duk inda kuke so. Firam ɗin yana daidaita kansa da abin da ke ciki.

<div id="gb-test"></div>
<script src="https://www.supergb.com/cbt/js/embed/v1.js"></script>
<script>
  GreenBridge.mount("#gb-test", { key: "pk_live_...", paper: "PAPER_ID" });
</script>

Jarrabawar ita ce id da mai ginin guntun lamba a console ɗinku ya nuna. Ƙara mode: "exam" don yanayin jarrabawa mai lokaci.

Gwajinku

Rubuta gwaje-gwaje a console ƙarƙashin Gwaje-gwaje kuma ku buɗe su. Idan ɗan takara ya shirya, sabar ɗinku tana fara gwaji:

curl -X POST https://www.supergb.com/cbt/partner-api/v1/sessions \
  -H "Authorization: Bearer $GREEN_BRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"test_id": "TEST_ID", "language": "fr", "candidate": {"id": "learner-42", "name": "Ada Obi", "email": "ada@example.com"}}'

candidate.id shi ne id ɗinku na mutumin, har haruffa 128. Suna da imel ba dole ba ne; abin da kuka aiko kaɗai muke ajiyewa.

language ba dole ba ne: ɗaya daga cikin de, en, es, fr, yo, ig, ha, nl, pt, sw. Maɓallai, agogo da saƙonnin gwajin za su bayyana a wannan harshe; tambayoyinku za su kasance yadda kuka rubuta su. Idan babu shi, gwajin zai kasance da Turanci.

Amsar tana ɗauke da adireshin farawa da ke aiki sau ɗaya, cikin mintuna 10. Buɗe shi a shafinku:

HTTP/1.1 201 Created

{
  "attempt_id": "att_...",
  "launch_token": "lt_...",
  "launch_url": "https://www.supergb.com/cbt/fr/embed/v1/test?launch=lt_...",
  "launch_expires_at": "2026-10-23T09:10:00Z",
  "live": true,
  "language": "fr"
}

<div id="gb-test"></div>
<script src="https://www.supergb.com/cbt/js/embed/v1.js"></script>
<script>
  GreenBridge.mountTest("#gb-test", {
    launchUrl: "LAUNCH_URL_FROM_YOUR_SERVER",
    onEvent: function (event) {
      if (event.type === "submitted") {
        showThanks(event.detail.attempt_id);
      }
    }
  });
</script>

Bayan an buɗe, gwaji yana ɗaukar har awanni 24, sake loda shafi kuma yana ci gaba da shi. Kowane ɗan takara yana yin kowane gwaji sau ɗaya.

Don lissafa gwaje-gwajenku da id ɗinsu:

curl https://www.supergb.com/cbt/partner-api/v1/tests -H "Authorization: Bearer $GREEN_BRIDGE_KEY"

Saƙonni daga firam

onEvent yana karɓar waɗannan, daga firam ɗinmu kaɗai:

Abu	Ma'ana
`ready`	Shafin ya gama lodawa.
`resize`	Tsawon abin da ke ciki ya canza. Firam ɗin yana bin sa da kansa.
`completed`	An yi wa jarrabawar gwaji maki. detail yana ɗauke da score da max_score.
`submitted`	An miƙa gwaji. detail yana ɗauke da attempt_id. Karɓi sakamakon daga sabar ɗinku, ba daga burauza ba.

Sakamako

Gwaje-gwajen da aka miƙa, sabbi a farko, 50 a kowane shafi. Tace ta test_id, candidate_id ko duka biyun.

curl "https://www.supergb.com/cbt/partner-api/v1/attempts?test_id=TEST_ID&page=0" -H "Authorization: Bearer $GREEN_BRIDGE_KEY"
curl https://www.supergb.com/cbt/partner-api/v1/attempts/ATTEMPT_ID -H "Authorization: Bearer $GREEN_BRIDGE_KEY"

Gwaji yana kama da wannan. questions yana ciki daga tsarin Growth zuwa sama.

{
  "id": "att_...",
  "test_id": "TEST_ID",
  "candidate_id": "learner-42",
  "live": true,
  "language": "fr",
  "started_at": "2026-10-23T09:02:11Z",
  "submitted_at": "2026-10-23T09:41:57Z",
  "integrity_events": 0,
  "score": 34.0,
  "max_score": 40.0,
  "percent": 85.0,
  "grading_status": "fully_graded",
  "questions": [
    {"question_id": "q1", "type": "multiple_choice_question", "score": 1.0, "max_score": 1.0}
  ]
}

grading_status shi ne fully_graded idan babu abin da ya rage don yin maki da hannu, in ba haka ba pending_manual_review ko pending_transcription.

Webhook

Ƙara adireshin https har 5 a console ɗinku. Ana aika kowane abu a matsayin POST mai sa hannu, ana kuma sake gwadawa har kwana 3 har sai sabar ɗinku ta amsa da matsayin 2xx.

Abu	Ma'ana
`attempt.started`	Ɗan takara ya buɗe gwajin.
`attempt.submitted`	Ɗan takara ya miƙa.
`attempt.graded`	Duk maki sun tabbata. Ana sake aikawa duk lokacin da maki ya canza.
`attempt.integrity_flagged`	Ɗan takara ya bar gwajin ko ya yi ƙoƙarin kwafa ko liƙa sau 3.
`ping`	Gwajin abu da aka aiko daga console ɗinku.

POST /hooks/green-bridge
Content-Type: application/json
Green-Bridge-Event: attempt.graded
Green-Bridge-Delivery: whd_...
Green-Bridge-Signature: t=1792834917,v1=5f0c...

{
  "id": "evt_graded_att_..._1",
  "type": "attempt.graded",
  "created_at": "2026-10-23T10:21:57Z",
  "data": { "id": "att_...", "candidate_id": "learner-42", "score": 34.0, "max_score": 40.0, "grading_status": "fully_graded" }
}

Id na abu ba ya canzawa, don haka kuna iya watsi da wanda kuka riga kuka yi aiki da shi ba tare da matsala ba.

Tabbatar da sa hannu

Ƙididdige HMAC-SHA256 na t, ɗigo ɗaya da jikin buƙatar kamar yadda yake, da sirrin sa hannunku, sannan ku kwatanta da v1. Ƙi lokacin da ya wuce mintuna biyar.

Node.js

const crypto = require("crypto");

function isFromGreenBridge(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(",").map(part => part.split("=")));
  if (!parts.t || !parts.v1 || Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) {
    return false;
  }
  const expected = crypto.createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex");
  return expected.length === parts.v1.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Python

import hashlib, hmac, time

def is_from_green_bridge(header, raw_body, secret):
    parts = dict(part.split("=", 1) for part in header.split(","))
    if "t" not in parts or abs(time.time() - int(parts["t"])) > 300:
        return False
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Kurakurai

Kurakurai suna dawowa a matsayin JSON da lambar da ba ta canzawa:

HTTP/1.1 404 Not Found

{"error": {"code": "test_not_found"}}

Lamba	HTTP	Ma'ana
`invalid_key`	401	Maɓallin ba ya nan, ba a san shi ba, ko an soke shi.
`partner_suspended`	403	An dakatar da asusunku. Tuntuɓe mu.
`live_keys_need_approval`	403	Maɓallan live suna aiki da zarar an amince da asusunku.
`not_on_plan`	403	Tsarinku bai ƙunshi wannan ba.
`test_not_found`	404	Babu gwajinku mai wannan id.
`attempt_not_found`	404	Babu gwajin da aka yi naku mai wannan id.
`candidate_not_found`	404	Ba ku da ɗan takara mai wannan id.
`test_not_open`	409	Ba a buɗe gwajin ba tukuna, ko an rufe shi.
`already_submitted`	409	Wannan ɗan takara ya riga ya miƙa wannan gwaji.
`invalid_request`	400	Wani fili ya ɓace ko bai zo a yadda ake tsammani ba.
`monthly_limit_reached`	429	Adadin wannan wata ya ƙare. Maɓallan gwaji suna ci gaba da aiki.
`internal_error`	500	Wani abu ya faru a ɓangarenmu. Sake gwadawa.

Iyaka da bayanai

Har buƙatu 300 a minti ɗaya ga kowane maɓallin sabar. Idan ya wuce haka, amsar ita ce 429 babu abin ciki; jira minti ɗaya ku sake gwadawa.
Gwaje-gwajen live da makin AI suna shiga adadin wata-wata na tsarinku. Ba a ƙirga gwajin da aka fara da maɓallin gwaji.

Bayananku

Abin da muke ajiyewa game da gwaje-gwajenku da 'yan takara, har tsawon wane lokaci, da yadda za ku dawo da shi.

Gwaje-gwaje da tambayoyinku: Ana ajiye su har sai kun goge su ko kun rufe asusunku.
'Yan takara: Id ɗin da kuka aiko, da suna da imel sai idan kun aiko su. Ana ajiye su har shekara ɗaya bayan an ga ɗan takarar na ƙarshe.
Zaman gwaji da sakamako: Amsoshi, rikodi, maki da abubuwan gaskiya. Ana ajiye su har shekara ɗaya bayan zaman ya fara, sannan a goge su.
Jarrabawar gwaji: Ana ajiye su shekara ɗaya, don ƙirga amfaninku kawai. Makin yana isa shafinku a cikin abin completed.
Isar da webhook: Ana ajiye su kwana 30, a cikin rajistar isarwa ta console ɗinku.
Amfani da API: Ƙididdiga ta kullum ga kowane maɓalli, ana ajiye su kwana 400, a shafin Amfani na console ɗinku.

Ku karɓi sakamako a kowane lokaci da GET /attempts. A tsarin Growth da Institution kuna kuma iya sauke sakamakon kowane gwaji a matsayin CSV daga menu na gwajin a console ɗinku: layi ɗaya ga kowane zaman gwaji tare da makin kowace tambaya, da amsar ɗan takara a tambayoyin da kuka rubuta. Tambayoyi daga bankin tambayoyin Green Bridge suna nuna makinsu kawai.

Don goge ɗan takara ɗaya da wuri:

curl -X POST https://www.supergb.com/cbt/partner-api/v1/candidates/erase \
  -H "Authorization: Bearer $GREEN_BRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"candidate_id": "learner-42"}'

Sakamakon da ɗan takara ya ajiye a asusunsa na Green Bridge nasa ne daga lokacin. Goge ɗan takarar ko rufe asusunku ba zai cire shi ba.

Mai asusunku zai iya rufe shi a ƙarƙashin Shafukan yanar gizo da maɓallai. Maɓallai da webhook suna tsayawa nan take kuma ana goge duk abin da ke sama cikin kwana ɗaya, don haka ku fara sauke abin da kuke buƙata.

Alƙawuran da ke bayan wannan suna cikin Abokan Hulɗa da Sarrafa Bayanai a cikin Sharuɗɗa da Ka'idoji namu.

Kuna buƙatar abin da tsare-tsaren ba su ƙunsa ba? Yi amfani da Tuntuɓe mu a shafin Tsari a console ɗinku.