شناسه‌های مستعار و سفارشی

شناسه مستعار (Alias) چیست؟

هر توکن می‌تواند یک شناسه مستعار اصلی داشته باشد که به شناسه کاربر سایت شما (موبایل، ایمیل، user id) مرتبط می‌شود. با setUserAliasID می‌توانید بدون ذخیره و مدیریت دستی توکن، نوتیفیکیشن را به همه دستگاه‌های یک کاربر بفرستید.

توکن FCM یا Subscriber ID؟ (توصیه‌شده)

همه وب‌سرویس‌های مدیریت Alias و Custom Aliases (ثبت، حذف و دریافت) در فیلد fcm_token هم توکن FCM و هم Subscriber ID را می‌پذیرند. روش توصیه‌شده این است که ابتدا Subscriber ID دستگاه را دریافت کنید و همان مقدار را به این وب‌سرویس‌ها بفرستید.

Subscriber ID شناسه ثابتی است که حتی پس از تجدید توکن FCM تغییر نمی‌کند، بنابراین امن‌تر و پایدارتر از توکن FCM است. برای نحوه دریافت آن به بخش «دریافت توکن و Subscriber ID» مراجعه کنید.

ثبت شناسه مستعار از جاوااسکریپت

بعد از login کاربر این متد را صدا بزنید. اگر کاربر قبلاً اجازه داده باشد، شناسه بلافاصله sync می‌شود؛ اگر بعداً اجازه دهد، شناسه ذخیره‌شده پس از دریافت توکن اعمال می‌شود.

await window.Pushfa.setUserAliasID('09351000000');

حذف شناسه مستعار (هنگام logout)

برای قطع ارتباط توکن از کاربر (مثلاً هنگام logout)، متد را بدون پارامتر صدا بزنید:

await window.Pushfa.setUserAliasID();

شناسه‌های سفارشی (Custom Aliases)

علاوه بر شناسه اصلی، هر مشترک می‌تواند چند شناسه برچسب‌دار داشته باشد؛ مثل crm_id، order_id یا email_hash. این دقیقاً همان مفهوم Aliases در OneSignal است. افزودن دوباره یک برچسب، مقدار قبلی را جایگزین می‌کند.

// یک شناسه
await window.Pushfa.addAlias('crm_id', 'CRM-123');

// چند شناسه با هم
await window.Pushfa.addAliases({ crm_id: 'CRM-123', tier: 'gold' });

// حذف یک شناسه
await window.Pushfa.removeAlias('crm_id');

// خواندن همه شناسه‌ها
const aliases = window.Pushfa.getAliases();

کنترل دسترسی Alias از جاوااسکریپت

در تنظیمات هر سرویس می‌توانید تعیین کنید عملیات ثبت، حذف یا دریافت Alias از طریق جاوااسکریپت (بدون کلید خصوصی) مجاز باشد یا نه. اگر غیرفعال باشد، این عملیات فقط از طریق وب‌سرویس بک‌اند قابل انجام است.

کلید خصوصی را هرگز در کد سمت کلاینت قرار ندهید. مدیریت Alias از بک‌اند همیشه مجاز است.

وب‌سرویس: ثبت شناسه مستعار

برای ثبت یا به‌روزرسانی Alias یک دستگاه از سمت سرور:

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
fcm_token	توکن FCM یا Subscriber ID دستگاه	بله
alias	شناسه مستعار جدید (مثلاً موبایل، ایمیل یا user id)	بله

curl -X POST https://pushfa.com/api/webservices/alias/set \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "fcm_token": "USER_FCM_TOKEN",
    "alias": "09351000000"
  }'

وب‌سرویس: حذف شناسه مستعار

برای حذف Alias یک دستگاه از سمت سرور (مثلاً هنگام logout کاربر):

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
fcm_token	توکن FCM یا Subscriber ID دستگاه	بله

curl -X POST https://pushfa.com/api/webservices/alias/delete \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "fcm_token": "USER_FCM_TOKEN"
  }'

وب‌سرویس: دریافت شناسه مستعار

برای خواندن Alias فعلی یک دستگاه از سمت سرور:

پاسخ: { "alias": "09351000000" } — اگر Alias ثبت نشده باشد مقدار null برمی‌گردد.

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
fcm_token	توکن FCM یا Subscriber ID دستگاه	بله

curl -X POST https://pushfa.com/api/webservices/alias/get \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "fcm_token": "USER_FCM_TOKEN"
  }'

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

برای ثبت یک یا چند Custom Alias با برچسب‌های دلخواه روی یک دستگاه. افزودن مجدد یک برچسب مقدار قبلی را جایگزین می‌کند.

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
fcm_token	توکن FCM یا Subscriber ID دستگاه	بله
aliases	آبجکت کلید-مقدار از برچسب و شناسه (مثل { "crm_id": "123" })	بله

curl -X POST https://pushfa.com/api/webservices/aliases/add \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "fcm_token": "USER_FCM_TOKEN",
    "aliases": { "crm_id": "CRM-123", "tier": "gold" }
  }'

وب‌سرویس: حذف شناسه‌های سفارشی

برای حذف یک یا چند Custom Alias با ارسال لیست برچسب‌ها:

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
fcm_token	توکن FCM یا Subscriber ID دستگاه	بله
labels[]	آرایه نام برچسب‌هایی که باید حذف شوند	بله

curl -X POST https://pushfa.com/api/webservices/aliases/remove \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "fcm_token": "USER_FCM_TOKEN",
    "labels": ["crm_id", "tier"]
  }'

وب‌سرویس: دریافت همه شناسه‌های سفارشی

برای خواندن تمام Custom Aliases ثبت‌شده روی یک دستگاه:

پاسخ: { "aliases": { "crm_id": "CRM-123", "tier": "gold" } }

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
fcm_token	توکن FCM یا Subscriber ID دستگاه	بله

curl -X POST https://pushfa.com/api/webservices/aliases/get \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "fcm_token": "USER_FCM_TOKEN"
  }'