লাইভ অ্যাক্টিভিটি স্কিমা এপিআই

একটি লাইভ অ্যাক্টিভিটি স্কিমা হল আপনার অ্যাপের একটি ActivityAttributes টাইপের জন্য একটি JSON স্কিমা (উদাহরণস্বরূপ FlightAttributes), যা কার্ডের উভয় অংশ কভার করে: ContentState ফিল্ডগুলি যা অ্যাক্টিভিটি চলাকালীন পরিবর্তিত হয়, এবং যে ফিল্ডগুলি এর পুরো জীবনকালের জন্য স্থির থাকে। একটি স্কিমা প্রকাশ করুন যাতে একটি জার্নির লাইভ অ্যাক্টিভিটি এলিমেন্ট একটি র’ JSON এডিটর এবং একটি ফ্রি-ফর্ম ফিল্ড তালিকার পরিবর্তে এটি থেকে উভয় অংশের জন্য নামযুক্ত ফিল্ড তৈরি করতে পারে। কার্ড এবং এর লেআউট এখনও আপনার অ্যাপের কোডে তৈরি করা হয়। স্কিমা শুধুমাত্র সেই ডেটা বর্ণনা করে যা একটি জার্নি পূরণ করে।

এই এপিআইটি ডেভেলপারদের জন্য যারা লাইভ অ্যাক্টিভিটি ইন্টিগ্রেট করছেন। অ্যাক্টিভিটি শুরু এবং আপডেট করার জন্য iOS লাইভ অ্যাক্টিভিটি এপিআই দেখুন।

স্কিমা লেখা

attributesType হল আপনার অ্যাপের সেই Swift টাইপের নাম যা ActivityAttributes-এর সাথে সঙ্গতিপূর্ণ। Pushwoosh আপনার কোড পড়ে না বা এর বিরুদ্ধে নাম যাচাই করে না — এটি শুধুমাত্র একটি স্ট্রিং যা এপিআই সংরক্ষণ করে এবং আপনি startLiveActivity-এর attributes-type ফিল্ডে পাস করেন।

jsonSchema সেই টাইপের উভয় অংশ কভার করে, দুটি ভিন্ন জায়গায়:

• ContentState ফিল্ডগুলি, যেগুলি অ্যাক্টিভিটি চলার সময় পরিবর্তিত হয়, যেমন একটি ফ্লাইটের গেট, স্ট্যাটাস, বা ETA, স্কিমার রুট properties-এ যায়।
• ActivityAttributes ফিল্ডগুলি, যা অ্যাক্টিভিটির পুরো জীবনকালের জন্য স্থির থাকে এবং এটি শুরু হওয়ার সময় একবার সেট করা হয়, যেমন একটি ফ্লাইট নম্বর, একটি পৃথক attributes সেকশনে যায়, যার নিজস্ব properties এবং একটি ঐচ্ছিক required তালিকা থাকে।

attributes সেকশনটি ঐচ্ছিক। এটি ছাড়া, ActivityAttributes ফিল্ডগুলি Live Activity এলিমেন্টে নামযুক্ত ফিল্ডের বদলে একটি ফ্রি ফিল্ড নাম/ভ্যালু তালিকা থেকে যায়। আপনি সবসময় startLiveActivity-তে live_activity.attributes-এর মাধ্যমে প্রকৃত অ্যাট্রিবিউট ভ্যালুগুলি পাস করেন — স্কিমা শুধুমাত্র তাদের নাম, টাইপ এবং কোনগুলি প্রয়োজনীয় তা ঘোষণা করে।

উদাহরণ

struct FlightAttributes: ActivityAttributes {
    struct ContentState: Codable, Hashable {
        var gate: String
        var status: String
        var estimatedTime: String
    }

    var flightNumber: String
}

flightNumber ActivityAttributes-এর মধ্যে থাকে। gate, status, এবং estimatedTime ContentState-এর মধ্যে থাকে। attributesType: "FlightAttributes"-এর জন্য স্কিমা হিসেবে উভয় অংশ প্রকাশ করুন:

{
  "type": "object",
  "properties": {
    "gate": { "type": "string" },
    "status": { "type": "string" },
    "estimatedTime": { "type": "string" }
  },
  "attributes": {
    "properties": {
      "flightNumber": { "type": "string" }
    },
    "required": ["flightNumber"]
  }
}

attributes-এর ভিতরে required লাইভ অ্যাক্টিভিটি এলিমেন্টের Start ধাপে flightNumber-কে বাধ্যতামূলক করে তোলে: সেখানে এটি খালি রাখলে প্রত্যাখ্যান করা হয়। ContentState ফিল্ডগুলির জন্য রুট properties-এ এমন কোনো তালিকা নেই। একটি জার্নির কখনোই gate, status, বা estimatedTime পূরণ করার প্রয়োজন হয় না।

একবার প্রকাশিত হলে, একটি জার্নির লাইভ অ্যাক্টিভিটি এলিমেন্ট এই আকারটি পড়ে Card content-এ gate, status, এবং estimatedTime-এর জন্য নামযুক্ত ফিল্ড অফার করে, একটি র’ কন্টেন্ট-স্টেট এডিটরের পরিবর্তে। Card attributes-এ flightNumber-এর জন্যও একই ঘটে, একটি ফ্রি ফিল্ড নাম/ভ্যালু তালিকার পরিবর্তে।

jsonSchema-তে প্রযোজ্য ফরম্যাট এবং অপরিবর্তনীয়তার নিয়মগুলির জন্য নীচের কনভেনশন দেখুন, এবং এপিআই সরাসরি কল না করে একই কাজ করার জন্য এই পৃষ্ঠার শেষে কন্ট্রোল প্যানেলে স্কিমা পরিচালনা দেখুন।

বেস ইউআরএল

https://rpc-api.svc-nue.pushwoosh.com

অথেন্টিকেশন

প্রতিটি অনুরোধে আপনার সার্ভার এপিআই টোকেন সহ একটি Authorization হেডার অন্তর্ভুক্ত করতে হবে:

Authorization: Api YOUR_API_TOKEN

কনভেনশন

• ফিল্ডের নামকরণ অপ্রতিসম। অনুরোধগুলি lowerCamelCase এবং প্রোটো নাম উভয়ই গ্রহণ করে। প্রতিক্রিয়াগুলি সর্বদা প্রোটো ফিল্ডের নামগুলির সাথে snake_case-এ ফিরে আসে (attributes_type, json_schema) — নীচের উদাহরণগুলিতে সেই কেসিং ব্যবহার করা হয়েছে।
• সংস্করণগুলি অপরিবর্তনীয়। একটি প্রকাশিত সংস্করণ সম্পাদনা করা যায় না — কোনো Update পদ্ধতি নেই। একই attributesType এবং version দিয়ে আবার প্রকাশ করলে AlreadyExists দিয়ে ব্যর্থ হয়। একটি উইজেট পরিবর্তন সর্বদা একটি নতুন সংস্করণ। Create-তে version বাদ দিন সেই attributesType-এর জন্য পরবর্তী বিনামূল্যে সংস্করণটি প্রকাশ করতে।
• jsonSchema ফরম্যাট: অবশ্যই "type": "object" সহ একটি JSON অবজেক্ট হতে হবে, যা 64 KB পর্যন্ত হতে পারে। null, একটি সংখ্যা, একটি খালি স্ট্রিং, বা "type": "object" ছাড়া একটি অবজেক্ট সবই প্রত্যাখ্যান করা হয়, কারণ Pushwoosh যে ফর্মটি তৈরি করে তার জন্য নামযুক্ত ফিল্ড প্রয়োজন, যা শুধুমাত্র একটি অবজেক্ট স্কিমার আছে। ঐচ্ছিক attributes সেকশন, যদি উপস্থিত থাকে, তা নিজেই একটি অবজেক্ট হতে হবে যার নিজস্ব properties এবং, ঐচ্ছিকভাবে, একটি required অ্যারে থাকবে যা শুধুমাত্র attributes.properties-এ ঘোষিত ফিল্ডের নাম দেয়। একটি ফিল্ডের নাম properties এবং attributes.properties উভয়েতেই থাকতে পারে না।

এন্ডপয়েন্ট

মেথড	পাথ	বিবরণ
GET	/api/live_activity_schemas	একটি অ্যাপ্লিকেশনের স্কিমা তালিকাভুক্ত করুন
GET	/api/live_activity_schemas/{attributesType}/{version}	একটি স্কিমা সংস্করণ পান
POST	/api/live_activity_schemas	একটি নতুন স্কিমা সংস্করণ প্রকাশ করুন
DELETE	/api/live_activity_schemas/{attributesType}/{version}	একটি স্কিমা সংস্করণ মুছুন

তালিকা

একটি অ্যাপ্লিকেশনের প্রতিটি attributesType-এর জন্য প্রকাশিত সমস্ত স্কিমা তাদের সংস্করণ সহ তালিকাভুক্ত করে, নতুন সংস্করণটি প্রথমে থাকে।

GET /api/live_activity_schemas

ক্যোয়ারী প্যারামিটার

প্যারামিটার	টাইপ	প্রয়োজনীয়	বিবরণ
application	string	হ্যাঁ	স্কিমা তালিকাভুক্ত করার জন্য অ্যাপ্লিকেশন কোড।
attributesType	string	না	তালিকাটি একটি ActivityAttributes টাইপের মধ্যে সীমাবদ্ধ করুন।

প্রতিক্রিয়ার উদাহরণ

{
  "schemas": [
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 2,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}",
      "created": "2026-09-01T10:00:00Z",
      "updated": "2026-09-01T10:00:00Z"
    },
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 1,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}}}",
      "created": "2026-08-15T10:00:00Z",
      "updated": "2026-08-15T10:00:00Z"
    }
  ]
}

পান

একটি স্কিমা সংস্করণ ফেরত দেয়।

GET /api/live_activity_schemas/{attributesType}/{version}

পাথ প্যারামিটার

প্যারামিটার	টাইপ	প্রয়োজনীয়	বিবরণ
attributesType	string	হ্যাঁ	ActivityAttributes টাইপের নাম।
version	integer	হ্যাঁ	স্কিমা সংস্করণ।

ক্যোয়ারী প্যারামিটার

প্যারামিটার	টাইপ	প্রয়োজনীয়	বিবরণ
application	string	হ্যাঁ	অ্যাপ্লিকেশন কোড যার সাথে স্কিমাটি সম্পর্কিত।

প্রতিক্রিয়া

উপরে তালিকা-তে দেখানো স্কিমা অবজেক্ট { "schema": { ... } } ফেরত দেয়।

তৈরি করুন

একটি attributesType-এর জন্য একটি নতুন স্কিমা সংস্করণ প্রকাশ করে। তৈরি করা স্কিমাটি ফেরত দেয়, যার মধ্যে এটি যে সংস্করণটি বরাদ্দ করা হয়েছিল তাও অন্তর্ভুক্ত থাকে।

POST /api/live_activity_schemas

অনুরোধের বডি

প্যারামিটার	টাইপ	প্রয়োজনীয়	বিবরণ
application	string	হ্যাঁ	অ্যাপ্লিকেশন কোড যেখানে স্কিমা প্রকাশ করতে হবে।
attributesType	string	হ্যাঁ	আপনার অ্যাপে ঘোষিত ActivityAttributes টাইপের নাম।
jsonSchema	string	হ্যাঁ	ContentState এবং attributes উভয়ের JSON স্কিমা। উপরে স্কিমা লেখা দেখুন।
version	integer	না	প্রকাশ করার জন্য সংস্করণ। এই attributesType-এর জন্য পরবর্তী বিনামূল্যে সংস্করণ পেতে বাদ দিন।

অনুরোধের উদাহরণ

{
  "application": "XXXXX-XXXXX",
  "attributesType": "FlightAttributes",
  "jsonSchema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}"
}

প্রতিক্রিয়া

তৈরি করা স্কিমা অবজেক্ট { "schema": { ... } } ফেরত দেয়।

সতর্কতা

একটি attributesType/version জোড়া যা ইতিমধ্যে বিদ্যমান তা প্রকাশ করলে AlreadyExists দিয়ে ব্যর্থ হয় — সংস্করণগুলি অপরিবর্তনীয়, তাই একটিকে ওভাররাইট করার কোনো উপায় নেই। পরবর্তী সংস্করণ পেতে version ছাড়া প্রকাশ করুন।

মুছুন

স্থায়ীভাবে একটি স্কিমা সংস্করণ মুছে ফেলে।

DELETE /api/live_activity_schemas/{attributesType}/{version}

পাথ প্যারামিটার

প্যারামিটার	টাইপ	প্রয়োজনীয়	বিবরণ
attributesType	string	হ্যাঁ	ActivityAttributes টাইপের নাম।
version	integer	হ্যাঁ	মুছে ফেলার জন্য স্কিমা সংস্করণ।

ক্যোয়ারী প্যারামিটার

প্যারামিটার	টাইপ	প্রয়োজনীয়	বিবরণ
application	string	হ্যাঁ	অ্যাপ্লিকেশন কোড যার সাথে স্কিমাটি সম্পর্কিত।

প্রতিক্রিয়া

সফল হলে একটি খালি অবজেক্ট ফেরত দেয়।

বিপদ

এটি ফিরিয়ে আনা যাবে না। মুছে ফেলা সংস্করণের বিরুদ্ধে তৈরি একটি জার্নির লাইভ অ্যাক্টিভিটি এলিমেন্ট তার ইতিমধ্যে সংরক্ষিত কন্টেন্ট এবং অ্যাট্রিবিউট ভ্যালু রাখে। এটি তখন থেকে উভয়ের জন্য কেবল ফর্মের ইঙ্গিতগুলি হারায়: কন্টেন্ট একটি র’ JSON এডিটরে ফিরে যায়, এবং অ্যাট্রিবিউট একটি ফ্রি ফিল্ড নাম/ভ্যালু তালিকায় ফিরে যায়।

ত্রুটির প্রতিক্রিয়া

HTTP স্ট্যাটাস	অর্থ
400 Bad Request	অবৈধ আর্গুমেন্ট: একটি প্রয়োজনীয় ফিল্ড অনুপস্থিত, jsonSchema উপরের ফরম্যাটের নিয়ম ব্যর্থ করে (একটি অবৈধ attributes সেকশন সহ), অথবা jsonSchema 64 KB অতিক্রম করে।
401 Unauthorized	অনুপস্থিত বা অবৈধ Authorization হেডার।
403 Forbidden	অ্যাপ্লিকেশনটি কলারের অ্যাকাউন্টের অন্তর্গত নয়।
404 Not Found	অ্যাপ্লিকেশন, বা attributesType/version জোড়া পাওয়া যায়নি।
409 Conflict	Create একটি attributesType/version জোড়া দিয়ে কল করা হয়েছিল যা ইতিমধ্যে বিদ্যমান (AlreadyExists on the wire)।
500 Internal Server Error	অপ্রত্যাশিত সার্ভার-সাইড ব্যর্থতা।

কন্ট্রোল প্যানেলে স্কিমা পরিচালনা

কন্ট্রোল প্যানেল এপিআই সরাসরি কল না করেই একই কাজ করার সুযোগ দেয়: টাইপ অনুযায়ী সংস্করণ তালিকাভুক্ত করা, একটি নতুন সংস্করণ প্রকাশ করা, একটি সংস্করণের JSON দেখা, এবং একটি সংস্করণ মুছে ফেলা (একটি নিশ্চিতকরণ সহ, কারণ মুছে ফেলা স্থায়ী)। ক্লিক পাথের জন্য iOS লাইভ অ্যাক্টিভিটি স্কিমা কনফিগারেশন দেখুন।