اتصال شناسه کاربر به پوشفا با Alias

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

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

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

شناسه ثابت مخاطب (Subscriber ID)؟ (توصیه‌شده)

همه وب‌سرویس‌های مدیریت Alias و شناسه‌های سفارشی (Custom Aliases) (ثبت، حذف و دریافت) در فیلد subscriber_id شناسه ثابت مخاطب (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	کلید خصوصی سرویس	بله
subscriber_id	شناسه ثابت مخاطب (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",
    "subscriber_id": "SUBSCRIBER_UUID",
    "alias": "09351000000"
  }'

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

POST

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

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

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
subscriber_id	شناسه ثابت مخاطب (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",
    "subscriber_id": "SUBSCRIBER_UUID"
  }'

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

POST

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

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

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

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
subscriber_id	شناسه ثابت مخاطب (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",
    "subscriber_id": "SUBSCRIBER_UUID"
  }'

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

POST

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

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

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
subscriber_id	شناسه ثابت مخاطب (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",
    "subscriber_id": "SUBSCRIBER_UUID",
    "aliases": { "crm_id": "CRM-123", "tier": "gold" }
  }'

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

POST

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

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

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
subscriber_id	شناسه ثابت مخاطب (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",
    "subscriber_id": "SUBSCRIBER_UUID",
    "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	کلید خصوصی سرویس	بله
subscriber_id	شناسه ثابت مخاطب (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",
    "subscriber_id": "SUBSCRIBER_UUID"
  }'