তৃতীয়-পক্ষ নোটিফিকেশন ইন্টিগ্রেশন

দ্রুত শুরু

Web Admin থেকে লক্ষ্য কোম্পানির সঙ্গে যুক্ত তৃতীয়-পক্ষ অ্যাপ তৈরি করুন। App ID ও App Secret কপি করুন; চূড়ান্ত ফল দরকার হলে ঐচ্ছিক Callback URL দিন। Engine যুক্ত কোম্পানির প্রতিটি সক্রিয় ও যোগ্য ব্যবহারকারীর জন্য নোটিফিকেশন সেন্টার রেকর্ড তৈরি করে এবং শুধু যোগ্য নিবন্ধিত ডিভাইসে সিস্টেম Push পাঠানোর চেষ্টা করে।

Endpoint ও প্রমাণীকরণ

API environment:

• Test: https://aim-api-test.proton-system.com
• Production: https://aim-api.proton-system.com

প্রতিটি server-to-server JSON request-এ HTTP Basic Authentication ব্যবহার করে Authorization: Basic Base64(KEY:SECRET) পাঠাতে হবে, যেখানে KEY হলো App ID এবং SECRET হলো App Secret:

Endpoint: POST /openapi/v1/notifications।

curl --request POST 'https://<your-engine-host>/openapi/v1/notifications' \
  --header 'Authorization: Basic <Base64(AppID:AppSecret)>' \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"order-20260819-001","title":"অর্ডার সম্পন্ন","body":"আপনার অর্ডার সম্পন্ন হয়েছে।","imageUrls":["https://cdn.example.com/order/001-1.webp","https://cdn.example.com/order/001-2.webp"]}'

অনুরোধের চুক্তি

কঠোর JSON-এ আবশ্যক requestId, title ও body-এর সঙ্গে ঐচ্ছিক imageUrls গ্রহণ করা হয়। imageUrls না পাঠানো, অথবা null বা [] পাঠানো মানে কোনো ছবি নেই; অন্যথায় প্রদর্শনের ক্রমে 1-9টি URL পাঠান। প্রতিটি মানের পাশের স্পেস বাদ দেওয়া হয়, মানটি অনন্য হতে হবে, username বা password ছাড়া সম্পূর্ণ HTTPS URL হতে হবে এবং সর্বোচ্চ 2048 Unicode অক্ষর হতে পারবে। একটি URL-ও অবৈধ হলে পুরো অনুরোধ বাতিল হয়। Engine URL সংরক্ষণ করে, কিন্তু ছবি আনে, যাচাই করে, proxy করে বা cache করে না। সম্পূর্ণ body সর্বোচ্চ 256 KiB; requestId 128 Unicode অক্ষর, title 100 এবং body 1000 অক্ষর পর্যন্ত। প্রতি App ID-এর সীমা মিনিটে 10 এবং ঘণ্টায় 100 অনুরোধ।

একই requestId, title, body এবং একই ক্রমের imageUrls পুনরায় পাঠালে সংরক্ষিত আগের ফল ফেরে; তাই প্রক্রিয়াকরণের পরে status ACCEPTED-এর বদলে SUCCESS, PARTIAL_SUCCESS অথবা FAILED হতে পারে। একই requestId ভিন্ন বিষয়বস্তু বা ছবির ক্রমে ব্যবহার করলে IDEMPOTENCY_CONFLICT ফেরে।

গ্রহণের প্রতিক্রিয়া

বৈধ অনুরোধ HTTP 202 ফেরায়:

{
  "requestId": "order-20260819-001",
  "notificationId": "00000000-0000-0000-0000-000000000001",
  "status": "ACCEPTED"
}

ACCEPTED শুধু বোঝায় Engine অনুরোধটি বিতরণের জন্য সংরক্ষণ করেছে; APNs/FCM বা ডিভাইসে প্রদর্শন নিশ্চিত করে না।

Callback ফলাফল

Callback URL থাকলে Engine চূড়ান্ত ফল পাঠায়:

{
  "requestId": "order-20260819-001",
  "status": "PARTIAL_SUCCESS",
  "recipientCount": 8,
  "pushAcceptedCount": 1,
  "pushFailedCount": 1
}

recipientCount হলো নোটিফিকেশন সেন্টারের প্রাপক ব্যবহারকারীর সংখ্যা। pushAcceptedCount ও pushFailedCount হলো Push Outbox ব্যাচের সংখ্যা; এগুলো ব্যবহারকারী বা ডিভাইসের সংখ্যা নয় এবং সিস্টেম ব্যানার পৌঁছানোর প্রমাণও নয়।

Callback পরীক্ষা

অ্যাডমিন প্যানেল থেকে প্রতিবার Callback পরীক্ষা করলে একটি স্বতন্ত্র প্রোব ইভেন্ট পাঠানো হয়:

{
  "requestId": "callback-test-<unique-id>",
  "status": "SUCCESS",
  "recipientCount": 1,
  "pushAcceptedCount": 1,
  "pushFailedCount": 0,
  "test": true
}

test এর মান true হলে গঠন যাচাই করে 2xx ফেরত দিন, তবে প্রোবটিকে পাঠানো কোনো নোটিফিকেশন অনুরোধের সঙ্গে মেলাবেন না এবং ব্যবসায়িক ডেলিভারি অবস্থা পরিবর্তন করবেন না। গণনাগুলো স্থির পরীক্ষামূলক মান; এগুলো প্রকৃত প্রাপক বা Push Outbox ব্যাচ নয়।

চূড়ান্ত status হলো SUCCESS, PARTIAL_SUCCESS অথবা FAILED। যেকোনো 2xx দিয়ে স্বীকার করুন; না হলে 1 মিনিট, 5 মিনিট, 30 মিনিট, 2 ঘণ্টা, 6 ঘণ্টা ও 24 ঘণ্টা পরে পুনরায় চেষ্টা হয়। বর্তমানে HMAC স্বাক্ষর নেই: HTTPS বাধ্যতামূলক করুন, পরীক্ষামূলক নয় এমন ফলাফলের requestId মিলিয়ে নিন, প্রবেশ সীমিত রাখুন এবং Callback idempotent ভাবে প্রক্রিয়া করুন।

ত্রুটির তালিকা

নিরাপত্তা ও পাঠানোর পরিধি

Mobile client প্রতিটি ছবির জন্য সর্বোচ্চ 5 MiB গ্রহণ করে এবং সম্পূর্ণ ছবি ডাউনলোড কার্যক্রম 10 সেকেন্ড পরে timeout হয়। Client 3xx redirect অনুসরণ করে না, তাই প্রতিটি URL-কে সরাসরি ছবি ফেরত দিতে হবে।

App ID ও App Secret কেবল server-to-server পরিচয়পত্র। browser, mobile app, প্রকাশ্য repository, URL বা client storage-এ রাখবেন না। ফাঁস হলে App Secret রিসেট করুন। যুক্ত কোম্পানির প্রতিটি সক্রিয় ও যোগ্য ব্যবহারকারী নোটিফিকেশন সেন্টার রেকর্ড পায় এবং recipientCount-এ গণনা হয়। সিস্টেম Push শুধু সক্রিয় PushInstallation এবং অনুমোদিত BUSINESS বিভাগের ডিভাইসে চেষ্টা করা হয়; তবুও প্রতিটি ডিভাইসে সিস্টেম ব্যানার নিশ্চিত নয়। imageUrls শুধু নোটিফিকেশনের detail-এ দেখানো হয়; Push বা Callback payload-এ যায় না। title ও body ছবির সাহায্য ছাড়াই সম্পূর্ণ ও বোধগম্য হতে হবে। ছবি ডাউনলোড বা প্রদর্শন ব্যর্থ হলেও accepted, Callback বা Push status পরিবর্তিত হয় না। Mobile client সরাসরি public CDN থেকে ছবি নামায়, তাই authentication বা Cookie ছাড়া URL ব্যবহার করুন, অন্তত 90 দিন উপলভ্য রাখুন এবং CDN যে ব্যবহারকারীর IP, request time ও User-Agent পাবে তা বিবেচনা করুন। ঐতিহাসিক প্রদর্শন স্থির রাখতে immutable object URL ব্যবহার করুন।