ضبط المستخدم والمصادقة

التكنولوجيا وراء الواجهة الصغيرة

متجر تذاكر ADITUS، منسوج بدلاً من نقله فوريًا. تعرض الواجهة الأمامية المصغرة تدفق الشراء الكامل محليًا في صفحتك - بدون إطار iframe أو جسم غريب مرئي. لقد تم تصميمه بشكل بسيط ومضيف أصلي، لذا فهو يبدو وكأنه موقعك الخاص، وليس عنصر واجهة مستخدم مضمن.

أمان الدفع، PCI وCSP

عادةً ما يؤدي دمج مكونات الطرف الثالث، مثل متاجر التذاكر، إلى إجراء مقايضة بين تجربة المستخدم والأداء وأمن تكنولوجيا المعلومات. تعمل الواجهة الأمامية الصغيرة على حل هذا التعارض من خلال نموذج مختلط: يتم عرض تدفق التفاعل في DOM الأصلي لصفحتك بينما تظل خطوة الدفع معزولة تمامًا - يحدث كل شيء غير ضار في صفحتك، ولا يحدث الدفع نفسه أبدًا.

كيف يختلف عن بدائل السوق

مقارنة النهج

كيف تحصل على الواجهة الأمامية الصغيرة

الواجهة الأمامية الصغيرة ليست على npm العامة وليست على CDN. يتم تسليمها كحزمة مصدر مباشرة من مثيل ADITUS الخاص بك: TypeScript وESM، مكتوبة بالكامل، بدون أي تبعيات وقت تشغيل خاصة بها - يقوم المجمع الخاص بك (Vite، webpack، Next.js، Nuxt) بتجميعها مع تطبيقك مثل التعليمات البرمجية الخاصة بك. اسم الاستيراد الموجود في المقتطفات الموجودة في هذه الصفحة (@workspace/aditus-shop-embed) هو اسم الحزمة من التكامل المرجعي الخاص بنا؛ الحزمة القابلة للتنزيل تحمل اسم @aditus/shop-embed — واجهة برمجة التطبيقات متطابقة. (API)

مضيفو SSR: Next.js وNuxt

الواجهة الأمامية الصغيرة مخصصة للعميل فقط. محتواه مباشر ومقيد بالجلسة - التوفر والأسعار وسلة تسوق المستخدم موجودة فقط لجلسة مصادق عليها في وقت الطلب، لذلك لا يوجد شيء ذو معنى يمكن للخادم المضيف عرضه مسبقًا. ينشئ mount() جذر React جديد من جانب العميل (createRoot)؛ لا يتم ترطيب العلامات المقدمة من الخادم داخل الحاوية. وهذا يجعل تكامل SSR بسيطًا ويمكن التنبؤ به: قم بعرض عنصر نائب على الخادم، وتثبيته على العميل، وحجز المساحة حتى لا يقفز أي شيء.

// Next.js (App Router) — das Micro-Frontend ist bewusst client-only.
"use client";
import { useEffect, useRef } from "react";
import { mount, type ShopHandle } from "@workspace/aditus-shop-embed";

export function TicketshopSection({ sessionToken }: { sessionToken: string }) {
  const el = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!el.current) return;
    const handle: ShopHandle = mount(el.current, {
      publicKey: "pk_deine_seite",
      sessionToken, // server-seitig gemintet, als Prop an die Client-Komponente
    });
    return () => handle(); // Unmount beim Routenwechsel
  }, [sessionToken]);

  // Server und Client rendern DENSELBEN Platzhalter — kein Hydration-Mismatch.
  // min-height reserviert den Platz, damit die Seite beim Mount nicht springt (CLS).
  return <div id="aditus-shop" ref={el} style={{ minHeight: 560 }} />;
}

تحتاج الواجهة الصغيرة إلى جلسة

import { mount } from "@workspace/aditus-shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount-Ziel #aditus-shop nicht gefunden");

// Ohne sessionToken bleibt das Micro-Frontend inaktiv: es zeigt nur einen
// neutralen Hinweis und startet KEINE API-Calls — kein Warenkorb,
// keine Registrierung, kein Checkout. Erst eine Session aktiviert den Shop.
mount(el, {
  publicKey: "pk_deine_seite",
  // sessionToken fehlt -> Shop wird nicht aktiviert.
});

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@workspace/aditus-shop-embed";

// getElementById kann null sein — in TypeScript sauber prüfen statt "!".
const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount-Ziel #aditus-shop nicht gefunden");

// AditusShopConfig typisiert alle Optionen — Autovervollständigung inklusive.
const config: AditusShopConfig = {
  publicKey: "pk_deine_seite", // Pflicht, sobald eine Session im Spiel ist
  sessionToken,                // vom Backend gemintet, nur im Speicher halten
};

const handle: ShopHandle = mount(el, config);

// Das Micro-Frontend sendet bei jedem Shop-Call den Header X-Aditus-Session.
// Beim Logout die Session serverseitig widerrufen und neu mounten/aktualisieren.

إعادة تحميل الصفحة لا تفقد الرحلة. تتذكر الواجهة الأمامية المصغرة عربة التسوق والخطوة محليًا، وتعيد جلب عربة التسوق المباشرة من الخادم الموجود على الحامل وتستمر تمامًا من حيث توقف المستخدم - على الرغم من أن صفحتك تطبع رمزًا مميزًا جديدًا للجلسة عند كل عملية تحميل. إذا انتهت صلاحية سلة التسوق من جانب الخادم، فستبدأ الرحلة من جديد ببساطة. لا يتعين على صفحتك أن تفعل أي شيء من أجل هذا.

هل تريد بداية جديدة متعمدة بدلاً من ذلك - زر حقيقي "للبدء من جديد"؟ تقوم الحزمة بتصدير ClearJourney(): اتصل بها قبل التثبيت (أو إعادة التثبيت) وسيتم إسقاط سجل الرحلة المستمر محليًا للصفحة الحالية، لذلك يبدأ التثبيت التالي من جديد عند نقطة الإدخال. تتم إزالة مؤشر السيرة الذاتية المحلي فقط؛ لم يتم تغيير أي حالة عربة تسوق من جانب الخادم.

اختياري: تصفح بشكل مجهول، قم بتسجيل الدخول عند الخروج

ليس عليك أن تعرف من هو المستخدم مقدمًا. يمكنك التثبيت مع جلسة ضيف وتتيح الواجهة الأمامية الصغيرة للزائر المجهول تصفح الأحداث واختيار المقالات وملء سلة التسوق. فقط عندما يتجاوزون عربة التسوق - باتجاه التسجيل والخروج - سيطلب منك تحديد المستخدم الحقيقي، عبر رد الاتصال onUserRequired. ثم يستمر باقي التدفق مع الحفاظ على العربة.

1. 1

   جبل مع جلسة ضيف

   لا يزال رمز الجلسة مطلوبًا لتنشيط المتجر - ولكن يمكن أن يكون جلسة ضيف: ما عليك سوى سكه دون حقل البريد الإلكتروني، ولا حاجة إلى عنوان نائب. يتصفح الزائر ويملأ العربة الموجودة تحته.

2. 2

   يؤدي ترك العربة إلى تشغيل onUserRequired

   في اللحظة التي يتقدم فيها الزائر عبر عربة التسوق، تستدعي الواجهة الأمامية الصغيرة رد الاتصال الخاص بك مرة واحدة وتظهر حالة معلقة محايدة. قم بتوثيق المستخدم (تسجيل الدخول/SSO)، ثم قم بإنشاء جلسة جديدة مرتبطة بالمستخدم بنفس الطريقة تمامًا مثل الجلسة الأولى: خادم إلى خادم مع سرك. ويتم إنشاء المستخدم اللاحق من خلال نظام التحويل من جهاز إلى جهاز أيضًا - لا يصل السر أبدًا إلى المتصفح ولا يتم تعيين المستخدم مطلقًا في رمز العميل. يقوم رد الاتصال الخاص بك فقط بترحيل الرمز غير الشفاف الناتج. والأهم من ذلك، أن الواجهة الخلفية لديك تستمد تلك الهوية من جلسة المصادقة الخاصة بها (ملف تعريف الارتباط/JWT)؛ يجب ألا يقبل أبدًا البريد الإلكتروني أو معرف المستخدم من المتصفح، وإلا يمكن لزائر ضار أن يطلب جلسة شخص آخر ويقرأ بياناته الشخصية عبر الملء المسبق.

3. 3

   قم بإرجاع الرمز المميز الجديد - يتم ترحيل العربة

   قم بإرجاع الرمز المميز للجلسة الجديدة وتقوم الواجهة الأمامية الصغيرة بتبديله وربط المستخدم المحدد بعربة التسوق الحالية - تبقى عربة التسوق ومقالاتها وأي فترات زمنية دون تغيير. ثم يدخل في التسجيل العودة فارغة للإجهاض - يبقى الزائر ببساطة في عربة التسوق، دون أي خطأ.

4. 4

   احذف onUserRequired لمستخدم ثابت

   إذا تركت رد الاتصال، فلن يتغير شيء من التدفق الكلاسيكي: قم بالتثبيت بجلسة مرتبطة بالمستخدم وتعمل الواجهة الأمامية الصغيرة مثل ذلك المستخدم منذ الخطوة الأولى.

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@workspace/aditus-shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount-Ziel #aditus-shop nicht gefunden");

// Ein GAST-Session-Token reicht zum Mounten: server-zu-server gemintet wie
// gehabt, nur OHNE das Feld email (keine Platzhalter-Adresse nötig). Der
// Besucher darf browsen UND den Warenkorb füllen, ohne dass ein konkreter
// Nutzer feststeht.
const config: AditusShopConfig = {
  publicKey: "pk_deine_seite",
  sessionToken: guestSessionToken,

  // Wird EINMAL aufgerufen, sobald der Besucher den Warenkorb Richtung
  // Registrierung verlässt. Hier authentifizierst du den Nutzer (Login/SSO)
  // und mintest server-zu-server eine NEUE, nutzergebundene Session.
  // Gib den frischen Token zurück -> das Micro-Frontend übernimmt ihn und baut
  // den Warenkorb unter dem identifizierten Nutzer neu auf (Artikel bleiben
  // erhalten). Gib null zurück, um abzubrechen -> der Besucher bleibt im
  // Warenkorb, ohne Fehler.
  onUserRequired: async () => {
    // Ruft NUR dein Backend auf – ohne Identität im Payload. Dein Backend liest
    // den eingeloggten Nutzer aus SEINER eigenen Session (Cookie/JWT) und mintet
    // server-seitig für GENAU diese Identität. Niemals die E-Mail aus dem Browser
    // übergeben – sonst könnte ein Angreifer hier eine fremde Adresse einsetzen
    // und über den Prefill an deren personenbezogene Daten gelangen.
    const res = await fetch("/api/shop/my-session", { method: "POST" });
    if (res.status === 401) return null;        // nicht eingeloggt -> im Warenkorb bleiben
    const { sessionToken } = (await res.json()) as { sessionToken: string };
    return sessionToken;
  },
};

const handle: ShopHandle = mount(el, config);

"إحصاءات Google‏ 4" / أحداث التجارة الإلكترونية (اختياري) (GA4)

يمكن للواجهة الأمامية الصغيرة الإبلاغ عن مسار التسوق إلى التحليلات الخاصة بك - ولكن فقط إذا طلبت ذلك. فهو لا يجمع أي gtag أو GTM أو GA SDK، ولا يقوم بتحميل أي شيء، ولا يقوم بتعيين أي ملفات تعريف ارتباط، ولا يرسل أي شيء من تلقاء نفسه. يمكنك إضافة رد اتصال اختياري واحد، onEvent، وتلقي الأحداث المكتوبة التي تم تشكيلها بالفعل في مخطط التجارة الإلكترونية المحسّنة على GA4 من Google. احذف oneEvent ولن يتغير شيء. إن الأداة التي تقوم بتغذيتها، وما إذا كانت لديك موافقة على إرسالها، تظل في صفك تمامًا.

import {
  mount,
  type ShopHandle,
  type ShopAnalyticsEvent,
} from "@workspace/aditus-shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount-Ziel #aditus-shop nicht gefunden");

const handle: ShopHandle = mount(el, {
  publicKey: "pk_deine_seite",
  sessionToken,
  // OPTIONAL. Lässt du onEvent weg, ändert sich nichts: das Micro-Frontend
  // sendet nichts, lädt kein gtag/GTM/GA-SDK und setzt keine Cookies.
  // Tool, Consent und Mapping bleiben komplett bei dir — hier GA4 via gtag.
  onEvent: (event: ShopAnalyticsEvent) => {
    // Consent liegt bei dir: erst senden, wenn der Nutzer zugestimmt hat.
    if (!hasAnalyticsConsent()) return;
    // Die Events sind bereits im GA4-Schema (name + items/value/currency ...),
    // also 1:1 an gtag durchreichen.
    const { name, ...params } = event;
    window.gtag?.("event", name, params);
  },
});

publicKey مقابل sessionToken

أبقِ الاثنين منفصلين. إنهم يجيبون على أسئلة مختلفة ويتم إقرانهم، وليسوا قابلين للتبادل.

نقطة النهاية ومرجع الاستجابة

في هذا العرض التوضيحي، يتم تنفيذ عملية سك العملة عبر الوكيل في المسارات المذكورة أعلاه. في الإنتاج، يتم سك الجلسة في قلب ADITUS — العقد مطابق. كلا الاستدعاءين من خادم إلى خادم: تتم مصادقة الواجهة الخلفية الخاصة بك باستخدام سر النعناع الخاص بعميلك (الذي تم إنشاؤه في وحدة تحكم مسؤول ADITUS) كرمز مميز لحاملها. نعناع واحد لكل تسجيل دخول هو النمط العادي؛ الرمز المميز الناتج هو كل ما يراه المتصفح على الإطلاق. (Bearer)

يمكنك تجربة هذا التدفق الدقيق باستخدام بيانات الاعتماد الخاصة بك فياختبار التكامل— النعناع، ​​جبل، المشي في الرحلة.

سك جلسة - طلب

سك جلسة – الرد (200)

إلغاء الجلسة

DELETE /api/shop/session/:token بنفس سر الحامل - يجب أن ينتمي السر إلى العميل الذي تم سك الجلسة من أجله. قم باستدعائه عند تسجيل الخروج حتى يموت الرمز المميز مع جلستك الخاصة. الاستجابة: { "تم إبطاله": صحيح } (أو خطأ إذا كانت الجلسة قد انتهت بالفعل). الإلغاء أمر غير فعال وآمن للحرق والنسيان. (Bearer)

الأخطاء واضحة