Gyorsindítás öt percben

A legrövidebb út egy működő telepítésig: a végén az appod a teszt-fiókodból olvas adatot, és fogad egy aláírt eseményt. Előfizetés és jóváhagyás nem kell hozzá.

1. 1

   1. lépés: Hozd létre a fejlesztői profilod

   Regisztrálj a /developer/register oldalon (cégnév, weboldal, Fejlesztői szerződés). Ha már van Dynex-fiókod, lépj be a /developer portálra, és hozd létre ott a profilod.

2. 2

   2. lépés: Hozz létre egy appot

   Add meg a nevet, az app_url-t és legalább egy redirect URI-t (pontos egyezés kell; helyi fejlesztéshez a http://localhost cím is megfelel). Kapsz egy client_id-t és egy client_secret-et - az utóbbi csak egyszer látszik, tárold biztonságosan.

3. 3

   3. lépés: Telepítsd a teszt-fiókra

   A portálon az app „Teszt-fiók” fülén hozd létre a teszt-fiókodat, majd kattints a „Telepítés a teszt-fiókra” gombra. A Dynex valódi code-dal küld az első regisztrált redirect URI-dra; a szervered ezt az exchangeAuthorizationCode() hívással kulcsra cseréli. A leggyorsabb, ha a példa-appból indulsz: a callback és a token-csere már benne van. Részletek: Teszt-fiók.

4. 4

   4. lépés: Hívd meg az API-t az SDK-val

   A token-csere válaszában kapott kulccsal (access_token) hívd a me() végpontot:

   1import { DynexClient } from "@dynex/app-sdk";2 3// A token-csere válaszából elmentett kulcs (dxk_…).4const dynex = new DynexClient({ accessToken: install.accessToken });5const me = await dynex.me();6console.log(me); // teszt-fiókos telepítésnél a válaszban sandbox: true áll

5. 5

   5. lépés: Fogadd az első webhookot

   Adj meg egy webhook URL-t az app „Webhookok” fülén (csak nyilvános https cím lehet; helyi géphez alagút kell), majd küldj teszt-eseményt a portálról. A fogadó mindkét csatornát ellenőrzi:

   1import { isAppChannelEvent, parseAppEvent, parseWebhookEvent, WebhookSignatureError } from "@dynex/app-sdk";2 3app.post("/webhooks", express.raw({ type: "*/*" }), (req, res) => {4  try {5    const event = isAppChannelEvent(req.headers)6      ? parseAppEvent(req.body, req.headers, process.env.DYNEX_EVENT_SECRET) // app.* események7      : parseWebhookEvent(req.body, req.headers, install.webhookSecret); // bérlői események8    console.log(event.event);9    res.status(200).end();10  } catch (e) {11    if (e instanceof WebhookSignatureError) return res.status(401).end();12    throw e;13  }14});

Ugyanez a hívás cURL-lel és az SDK-val, a szerződésből generálva:

1curl -X GET 'https://prod.dynex.hu/api/v3/me' \2  -H 'Authorization: Bearer dxk_A_TELEPITES_KULCSA' \3  -H 'Accept: application/json'

1// Node.js 18+ (beépített fetch, nem kell külön csomag).2async function main() {3  const res = await fetch("https://prod.dynex.hu/api/v3/me", {4    method: "GET",5    headers: {6      "Authorization": "Bearer dxk_A_TELEPITES_KULCSA",7      "Accept": "application/json"8    }9  });10 11  const data = await res.json();12  console.log(res.status, data);13}14 15main().catch(console.error);

1. 1

   1. lépés: Fejlesztői profil

   A fejlesztői portál külön réteg: nem kell hozzá Dynex-előfizetés. Regisztrálj a /developer/register oldalon (cégnév, weboldal, Fejlesztői szerződés), vagy ha már van Dynex-fiókod, lépj be a /developer portálra és hozd létre ott a profilod (kapcsolati e-mail, számlázási adatok a profilban).

2. 2

   2. lépés: Új app

   Add meg a nevet, slugot, leírást, az app_url-t (https), a redirect URI-kat (pontos egyezés!), a webhook URL-t, a kért hatóköröket, a beágyazott menüpontokat (path + title) és az árat. Kapsz egy client_id-t és egy client_secret-et - az utóbbi csak egyszer látszik, tárold biztonságosan.

3. 3

   3. lépés: SDK

   Töltsd le az SDK-csomagot (dynex-app-sdk.tgz) és telepítsd: npm install ./dynex-app-sdk.tgz (vagy indulj a példa-appból). Töltsd ki a .env-t a client_id / client_secret párral.

4. 4

   4. lépés: OAuth-indítás

   Egy „Telepítés a Dynexbe” gomb a buildAuthorizeUrl() által épített címre visz. A folyamat leírása: OAuth és hatókörök.

5. 5

   5. lépés: Callback

   A redirect URI-don a code-ot exchangeAuthorizationCode()-dal kulcsra cseréled, és a választ (kulcs, install_id, tenant_id, embed_secret, webhook_secret) bérlőnként elmented. A Dynex piacteréről indított telepítésnél a code state nélkül, az ELSŐ regisztrált redirect URI-dra érkezik - readMarketplaceCallbackParams()-szal fogadd, és a válasz tenant_id-ját mutasd meg a felhasználónak megerősítésre. A sikeres csere után küldd vissza a bérlőt a Dynexbe: buildMarketplaceReturnUrl({ slug }) = /app/marketplace/<slug>?telepitve=1 - a piactéri oldal ott a „telepítve” visszajelzést mutatja.

6. 6

   6. lépés: Teszt-telepítés

   A legegyszerűbb út a teszt-fiók: a portálon az app „Teszt-fiók” fülén egy kattintással telepíted, mintaadatokra, jóváhagyás nélkül. Ha van saját Dynex-fiókod, a régi út is megmaradt: draft állapotban az app olyan fiókra telepíthető, ahol te tag vagy. A piactér listája csak jóváhagyott appot mutat: a draft appot a szerkesztő „Telepítés a tesztfiókra” gombjával (a közvetlen /app/marketplace/<slug> címen) vagy az OAuth-linkről telepítsd a saját fiókodra.

7. 7

   7. lépés: API-hívás

   new DynexClient({ accessToken }) - próbáld a me()-t, majd a valódi végpontokat.

8. 8

   8. lépés: Beágyazás

   Az app_url + embeds[].path oldalad olvassa a dynex_token paramétert, ellenőrzi (verifyEmbedToken), a böngészőben pedig a createAppBridge() hívja a ready()-t és az autoResize()-t. Részletek: Beágyazott oldalak.

9. 9

   9. lépés: Webhook

   A telepítéskor a Dynex automatikusan feliratkozik az app default_webhook_events eseményeire a webhook URL-eden; a fogadóban parseWebhookEvent() ellenőrzi az aláírást. Ugyanerre a címre jönnek az app életciklus-eseményei is (telepítés, eltávolítás, jóváhagyás) - azokat a parseAppEvent() fogadja, másik titokkal.

10. 10

    10. lépés: Beküldés

    A fejlesztői portálon „Beküldés jóváhagyásra”. A tulajdonos jóváhagyja, visszaküldi megjegyzéssel vagy elutasítja; jóváhagyás után az app megjelenik a marketplace-en. Részletek: Adatlap, beküldés, szabályzat.

• OAuth és hatókörökA hozzájárulás, a token-csere és a hibakódok.
• Webhookok és eseményekAláírás, újrapróbálás, életciklus-események.
• Beágyazott oldalakA kontextus-token és a híd.
• SDK és példa-appA csomag tartalma és a letöltések.