مستندات راهنمای کاربر ارسال و هدف‌گیری شناسه‌های مستعار و سفارشی

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

ربط دادن توکن مشترک به شناسه داخلی سایت شما (Alias) و مدیریت شناسه‌های سفارشی چندگانه (Custom Aliases).

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

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

در تمام مستندات و APIهای پوشفا، external_id دقیقاً به معنی همین Alias عادی و اصلی است و شناسه جداگانه‌ای محسوب نمی‌شود. Custom Alias متفاوت است: با ساختار aliases[label] ارسال می‌شود و هر پروفایل می‌تواند چند Custom Alias برچسب‌دار داشته باشد.

توکن 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 از بک‌اند همیشه مجاز است.

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

POST
https://pushfa.com/api/webservices/alias/set

ثبت یا به‌روزرسانی 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"
  }'

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

POST
https://pushfa.com/api/webservices/alias/delete

حذف 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"
  }'

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

POST
https://pushfa.com/api/webservices/alias/get

خواندن 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"
  }'

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

POST
https://pushfa.com/api/webservices/aliases/add

ثبت یک یا چند 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" }
  }'

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

POST
https://pushfa.com/api/webservices/aliases/remove

حذف یک یا چند 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"]
  }'

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

POST
https://pushfa.com/api/webservices/aliases/get

خواندن تمام 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"
  }'
Ctrl+I