پیکربندی SDK (SDK Configuration)

راهنمای کامل اتریبیوت‌های SDK فیدگاه، روش‌های یکپارچه‌سازی و نمونه کد برای فریم‌ورک‌های محبوب JavaScript.

SDK فیدگاه از طریق اتریبیوت‌های HTML پیکربندی می‌شود. این اتریبیوت‌ها را می‌توانید به دو شکل متفاوت اعمال کنید تا رفتار ابزارک را دقیقاً مطابق نیاز خود تنظیم کنید.

روش‌های استفاده از اتریبیوت‌ها

روش اول — تگ `<script>` اصلی (تنظیمات سراسری)

اتریبیوت‌هایی که مستقیماً روی تگ اسکریپت تعریف می‌کنید، به‌عنوان تنظیمات پیش‌فرض برای کل سایت اعمال می‌شوند.

<script
  src="https://fidegah.ir/api/sdk.js"
  data-sdk-token="YOUR_WORKSPACE_TOKEN"
  data-layout="sidebar"
  data-position="right"
  data-theme="light"
  data-size="default"
  data-blur="false"
  data-button="true"
></script>

روش دوم — دکمه‌های سفارشی (تنظیمات محلی)

هر عنصر HTML که دارای اتریبیوت data-fidegah-toggle باشد می‌تواند تنظیمات مختص خودش را داشته باشد. این تنظیمات محلی همیشه بر تنظیمات سراسری اسکریپت اولویت دارند.

<button
  data-fidegah-toggle
  data-layout="modal"
  data-position="right"
  data-theme="dark"
>
  ارسال بازخورد
</button>

این مکانیزم Override به شما اجازه می‌دهد در بخش‌های مختلف سایت، ابزارک را با ظاهر و رفتار متفاوت باز کنید؛ بدون اینکه تنظیمات سراسری را تغییر دهید.

فهرست اتریبیوت‌ها

`data-sdk-token`

توکن فضای‌کاری (Workspace) شما برای احراز هویت در فیدگاه. این اتریبیوت اجباری است و بدون آن SDK بارگذاری نمی‌شود.

ویژگی	مقدار
محل استفاده	فقط روی تگ `<script>` اصلی
اجباری	بله
نوع مقدار	رشته — توکن دریافتی از پنل مدیریت

<script
  src="https://fidegah.ir/api/sdk.js"
  data-sdk-token="fg_sdk_xxxxxxxxxxxxxxxx"
></script>

توکن SDK با کلید مخفی (Secret Key) فرق دارد و برای استفاده در فرانت‌اند طراحی شده است. با این حال از قرار دادن آن در مخازن عمومی Git خودداری کنید.

برای دریافت SDK Token مراحل زیر را دنبال کنید :

وارد داشبورد مدیریت فیدگاه شوید و به مسیر تنظیمات > فضاهای‌کاری > تنظیمات SDK بروید.

SDK Token را کپی کنید.

ثبت دامنه‌های مجاز

برای جلوگیری از سوءاستفاده از توکن شما، حتماً باید دامنه‌های وب‌سایت خود را در پنل ثبت کنید. در غیر این صورت، درخواست‌های SDK از طرف وب‌سایت شما رد خواهند شد.

اگر دامنه‌ای در این بخش ثبت نشده باشد، SDK در آن وب‌سایت بارگذاری نخواهد شد و با خطای عدم دسترسی مواجه می‌شوید.

برای اضافه کردن دامنه‌های مجاز از همان صفحه تنطیمات SDK اقدام کنید.

نکته برای محیط توسعه

شما می‌توانید آدرس‌های محلی مانند localhost یا IP های محلی (به همراه پورت مربوطه، مثلاً localhost:3000) را نیز در لیست دامنه‌های مجاز وارد کنید تا در فرآیند پیاده‌سازی و تست روی سیستم خود دچار مشکل نشوید.

`data-layout`

شکل کلی و چیدمان هندسی ابزارک را تعیین می‌کند. روی موبایل، ابزارک همیشه به صورت تمام‌صفحه نمایش داده می‌شود و این تنظیم تأثیری ندارد.

ویژگی	مقدار
پیش‌فرض	`sidebar`
مقادیر مجاز	`sidebar` \| `floating` \| `modal`

مقدار	رفتار
`sidebar`	منوی کشویی تمام‌قد که از کناره صفحه وارد می‌شود
`floating`	کارت شناور مدرن با لبه‌های گرد و فاصله از کناره‌ها
`modal`	باکس متمرکز در وسط صفحه با پس‌زمینه تاریک

<script src="https://fidegah.ir/api/sdk.js" data-layout="floating" ...></script>

`data-position`

جهت قرارگیری ابزارک روی صفحه و جهت انیمیشن ورود آن را مشخص می‌کند. در حالت modal این تنظیم روی جهت انیمیشن ورود تأثیر ندارد و ابزارک همیشه از مرکز بزرگ می‌شود.

ویژگی	مقدار
پیش‌فرض	`right`
مقادیر مجاز	`right` \| `left` \| `top` \| `bottom`

مقدار	رفتار
`right`	ابزارک در سمت راست قرار می‌گیرد، انیمیشن از راست به چپ
`left`	ابزارک در سمت چپ قرار می‌گیرد، انیمیشن از چپ به راست
`top`	ابزارک به سقف صفحه متصل می‌شود، انیمیشن از بالا به پایین
`bottom`	ابزارک به کف صفحه متصل می‌شود، انیمیشن از پایین به بالا

<script src="https://fidegah.ir/api/sdk.js" data-position="left" ...></script>

`data-theme`

رنگ‌بندی کلی ابزارک را با پوسته سایت میزبان هماهنگ می‌کند.

ویژگی	مقدار
پیش‌فرض	`light`
مقادیر مجاز	`light` \| `dark`

مقدار	رفتار
`light`	پس‌زمینه روشن با کادرها و متن‌های کم‌رنگ
`dark`	پس‌زمینه تیره دودی، مناسب برای سایت‌هایی با Dark Mode

<script src="https://fidegah.ir/api/sdk.js" data-theme="dark" ...></script>

`data-size`

پهنا یا ارتفاع ابزارک را در حالت‌های sidebar و modal کنترل می‌کند. در حالت floating این تنظیم تأثیری ندارد.

ویژگی	مقدار
پیش‌فرض	`default`
مقادیر مجاز	`default` \| `half` \| `full`

مقدار	رفتار
`default`	ابعاد استاندارد — عرض ۴۵۰ پیکسل
`half`	نیمی از صفحه — `50vw` برای sidebar و `50vh` برای modal
`full`	تمام‌صفحه — `100vw` یا `100vh`

<script src="https://fidegah.ir/api/sdk.js" data-size="half" ...></script>

`data-blur`

یک افکت شیشه‌ای روی محتوای پشت ابزارک اعمال می‌کند تا توجه کاربر روی ابزارک متمرکز شود.

ویژگی	مقدار
پیش‌فرض	`false`
مقادیر مجاز	`true` \| `false`

مقدار	رفتار
`false`	محتوای پشتی فقط کمی تاریک می‌شود
`true`	افکت Backdrop Blur فعال می‌شود و پس‌زمینه مات می‌شود

<script src="https://fidegah.ir/api/sdk.js" data-blur="true" ...></script>

`data-button`

یک دکمه شناور آماده را در گوشه صفحه رندر می‌کند. اگر می‌خواهید دکمه باز‌کننده ابزارک را خودتان طراحی کنید، این گزینه را روی false نگه دارید.

ویژگی	مقدار
محل استفاده	فقط روی تگ `<script>` اصلی
پیش‌فرض	`false`
مقادیر مجاز	`true` \| `false`

مقدار	رفتار
`false`	هیچ دکمه‌ای به صفحه اضافه نمی‌شود
`true`	دکمه «ثبت بازخورد» با انیمیشن هاور در گوشه صفحه ظاهر می‌شود

<script src="https://fidegah.ir/api/sdk.js" data-button="true" ...></script>

`data-fidegah-toggle`

هر عنصر HTML را به دکمه باز و بسته‌کننده ابزارک تبدیل می‌کند. این اتریبیوت مقداری دریافت نمی‌کند و صرف وجودش روی عنصر کافی است.

ویژگی	مقدار
نوع	Flag — نیازی به مقدار ندارد
محل استفاده	روی هر عنصر HTML دلخواه

<!-- دکمه معمولی -->
<button data-fidegah-toggle>ثبت بازخورد</button>

<!-- لینک -->
<a href="#" data-fidegah-toggle>ارسال نظر</a>

<!-- هر عنصر دلخواه -->
<span data-fidegah-toggle>
  <svg ... />
</span>

نمونه‌های یکپارچه‌سازی در فریم‌ورک‌ها

یک کامپوننت مجزا برای بارگذاری SDK بسازید و آن را در root اپ خود قرار دهید. با این رویکرد، اسکریپت فقط یک بار لود می‌شود و با تغییر کاربر لاگین‌شده، هویت به‌روزرسانی می‌شود.

src/components/FidegahSDK.tsx

import { useEffect } from "react";

interface FidegahSDKProps {
  userId?: string;
  userName?: string;
  userEmail?: string;
  userToken?: string;
}

export function FidegahSDK({
  userId,
  userName,
  userEmail,
  userToken,
}: FidegahSDKProps) {
  useEffect(() => {
    if (typeof window === "undefined") return;

    const script = document.createElement("script");
    script.src = "https://fidegah.ir/api/sdk.js";
    script.setAttribute("data-sdk-token", process.env.REACT_APP_FIDEGAH_TOKEN!);
    script.setAttribute("data-layout", "sidebar");
    script.setAttribute("data-position", "right");
    script.setAttribute("data-theme", "light");
    script.setAttribute("data-button", "true");

    const identifyUser = () => {
      if (userId && (window as any).Fidegah) {
        (window as any).Fidegah.identify({
          id: userId,
          name: userName,
          email: userEmail,
          token: userToken,
        });
      }
    };

    script.onload = identifyUser;
    document.body.appendChild(script);

    // اگر اسکریپت قبلاً لود شده و کاربر تغییر کرده باشد
    if ((window as any).Fidegah) {
      identifyUser();
    }

    return () => {
      document.body.removeChild(script);
    };
  }, [userId, userName, userEmail, userToken]);

  return null;
}

src/App.tsx

import { FidegahSDK } from "./components/FidegahSDK";
import { useAuth } from "./hooks/useAuth";

export default function App() {
  const { user } = useAuth();

  return (
    <>
      <FidegahSDK
        userId={user?.id}
        userName={user?.name}
        userEmail={user?.email}
        userToken={user?.fidegahToken}
      />
      {/* بقیه اپ */}
    </>
  );
}

در Next.js از کامپوننت بومی <Script> استفاده کنید و شناسایی کاربر را در یک کامپوننت کلاینت مجزا مدیریت کنید تا با لود ناهمگام اسکریپت تداخلی نداشته باشد.

components/FidegahIdentify.tsx

"use client";

import { useEffect } from "react";
import { useSession } from "next-auth/react";

export function FidegahIdentify() {
  const { data: session } = useSession();

  useEffect(() => {
    if (!session?.user) return;

    const identify = () => {
      if ((window as any).Fidegah) {
        (window as any).Fidegah.identify({
          id: session.user.id,
          name: session.user.name,
          email: session.user.email,
          token: session.user.fidegahToken,
        });
      }
    };

    // اجرای احراز هویت (اگر اسکریپت لود شده باشد)
    identify();

    // برای اطمینان در صورتی که اسکریپت بعداً لود شود
    window.addEventListener("load", identify);
    return () => window.removeEventListener("load", identify);
  }, [session]);

  return null;
}

app/layout.tsx

import Script from "next/script";
import { FidegahIdentify } from "@/components/FidegahIdentify";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="fa" dir="rtl">
      <body>
        <FidegahIdentify />
        {children}
        <Script
          src="https://fidegah.ir/api/sdk.js"
          data-sdk-token={process.env.NEXT_PUBLIC_FIDEGAH_TOKEN}
          data-layout="sidebar"
          data-position="right"
          data-theme="light"
          data-button="true"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

توکن امضا (fidegahToken) را از یک Server Action یا API Route دریافت کنید تا FIDEGAH_SECRET_KEY هرگز به فرانت‌اند نرسد.

در Vue 3، اسکریپت را به صورت پویا بارگذاری کنید. با این کار از عدم اجرای کدهای مربوط به مرورگر در محیط SSR مطمئن می‌شوید.

src/App.vue

<template>
  <RouterView />
</template>

<script setup lang="ts">
import { onMounted, watch } from "vue";
import { useAuthStore } from "@/stores/auth";

const authStore = useAuthStore();

function loadFidegah() {
  if (typeof window === "undefined") return;

  const script = document.createElement("script");
  script.src = "https://fidegah.ir/api/sdk.js";
  script.setAttribute("data-sdk-token", import.meta.env.VITE_FIDEGAH_TOKEN);
  script.setAttribute("data-layout", "floating");
  script.setAttribute("data-position", "right");
  script.setAttribute("data-theme", "light");
  script.setAttribute("data-button", "true");

  script.onload = () => identifyUser();
  document.body.appendChild(script);

  // اگر اسکریپت از قبل لود شده باشد (مثلاً در سناریوهای خاص ناوبری)
  if ((window as any).Fidegah) {
    identifyUser();
  }
}

function identifyUser() {
  const user = authStore.currentUser;
  if (!user || !(window as any).Fidegah) return;

  (window as any).Fidegah.identify({
    id: user.id,
    name: user.name,
    email: user.email,
    token: user.fidegahToken,
  });
}

onMounted(() => loadFidegah());

// با تغییر اطلاعات کاربر، هویت او مجدداً به SDK اعلام می‌شود
watch(
  () => authStore.currentUser,
  () => identifyUser(),
  { deep: true },
);
</script>

در Nuxt 3 بهترین روش ایجاد یک Client Plugin برای تزریق اسکریپت و صدا زدن متد شناسایی در لایوت اصلی با رعایت شروط SSR است.

plugins/fidegah.client.ts

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();

  useHead({
    script: [
      {
        src: "https://fidegah.ir/api/sdk.js",
        "data-sdk-token": config.public.fidegahToken,
        "data-layout": "sidebar",
        "data-position": "right",
        "data-theme": "light",
        "data-button": "true",
        tagPosition: "bodyClose",
      },
    ],
  });
});

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    fidegahSecretKey: process.env.FIDEGAH_SECRET_KEY, // فقط در سمت سرور
    public: {
      fidegahToken: process.env.NUXT_PUBLIC_FIDEGAH_TOKEN, // در دسترس فرانت‌اند
    },
  },
});

layouts/default.vue

<script setup lang="ts">
import { watchEffect } from "vue";

const { data: session } = useAuth();

function identifyUser() {
  if (
    typeof window === "undefined" ||
    !(window as any).Fidegah ||
    !session.value?.user
  )
    return;

  (window as any).Fidegah.identify({
    id: session.value.user.id,
    name: session.value.user.name,
    email: session.value.user.email,
    token: session.value.user.fidegahToken,
  });
}

// گوش دادن به تغییرات وضعیت لاگین کاربر و وضعیت لود شدن کامل صفحه
watchEffect(() => {
  if (session.value?.user) {
    identifyUser();

    // اگر اسکریپت هنوز لود نشده، به محض لود کامل پنجره دوباره تلاش کن
    if (typeof window !== "undefined" && !(window as any).Fidegah) {
      window.addEventListener("load", identifyUser);
    }
  }
});
</script>

<template>
  <slot />
</template>

در SvelteKit، اسکریپت را در +layout.svelte بارگذاری کنید و توکن امضا را در +layout.server.ts تولید کنید تا Secret Key هیچ‌وقت به مرورگر نرسد.

src/routes/+layout.svelte

<script lang="ts">
  import { onMount } from "svelte";

  let { data, children } = $props();

  function identifyUser() {
    if (typeof window !== "undefined" && data.user && (window as any).Fidegah) {
      (window as any).Fidegah.identify({
        id: data.user.id,
        name: data.user.name,
        email: data.user.email,
        token: data.user.fidegahToken,
      });
    }
  }

  onMount(() => {
    const script = document.createElement("script");
    script.src = "https://fidegah.ir/api/sdk.js";
    script.setAttribute("data-sdk-token", import.meta.env.PUBLIC_FIDEGAH_TOKEN);
    script.setAttribute("data-layout", "sidebar");
    script.setAttribute("data-position", "right");
    script.setAttribute("data-theme", "light");
    script.setAttribute("data-button", "true");

    script.onload = identifyUser;
    document.body.appendChild(script);

    if ((window as any).Fidegah) {
      identifyUser();
    }

    return () => {
      document.body.removeChild(script);
    };
  });

  $effect(() => {
    if (data.user) identifyUser();
  });
</script>

{@render children()}

src/routes/+layout.server.ts

export async function load({ locals }) {
  const user = locals.session?.user;
  if (!user) return { user: null };

  const fidegahToken = generateFidegahToken(user.id);
  return { user: { ...user, fidegahToken } };
}

ترکیب دکمه‌های سفارشی

با استفاده از data-fidegah-toggle می‌توانید در بخش‌های مختلف سایت، ابزارک را با ظاهر و رفتار متفاوت باز کنید:

<!-- دکمه پیش‌فرض — از تنظیمات سراسری اسکریپت پیروی می‌کند -->
<button data-fidegah-toggle>بازخورد کلی</button>

<!-- مودال تاریک با blur برای گزارش باگ -->
<button
  data-fidegah-toggle
  data-layout="modal"
  data-theme="dark"
  data-blur="true"
>
  گزارش مشکل
</button>

<!-- sidebar در سمت چپ برای پیشنهاد قابلیت -->
<button data-fidegah-toggle data-layout="sidebar" data-position="left">
  پیشنهاد قابلیت
</button>

خلاصه اتریبیوت‌ها

اتریبیوت	پیش‌فرض	مقادیر مجاز	محل استفاده
`data-sdk-token`	—	رشته توکن	فقط `<script>`
`data-layout`	`sidebar`	`sidebar` \| `floating` \| `modal`	هر دو
`data-position`	`right`	`right` \| `left` \| `top` \| `bottom`	هر دو
`data-theme`	`light`	`light` \| `dark`	هر دو
`data-size`	`default`	`default` \| `half` \| `full`	هر دو
`data-blur`	`false`	`true` \| `false`	هر دو
`data-button`	`false`	`true` \| `false`	فقط `<script>`
`data-fidegah-toggle`	—	Flag (بدون مقدار)	دکمه‌های سفارشی

پیکربندی SDK (SDK Configuration)

On this page