लाइव एक्टिविटी स्कीमा API

एक लाइव एक्टिविटी स्कीमा आपके ऐप में एक ActivityAttributes प्रकार (उदाहरण के लिए FlightAttributes) के लिए एक JSON स्कीमा है, जो कार्ड के दोनों हिस्सों को कवर करती है: ContentState फ़ील्ड जो एक्टिविटी के चलने के दौरान बदलते हैं, और वे फ़ील्ड जो इसके पूरे जीवनकाल के लिए स्थिर रहते हैं। एक स्कीमा प्रकाशित करें ताकि एक journey का लाइव एक्टिविटी एलिमेंट एक रॉ JSON एडिटर और एक फ्री-फॉर्म फ़ील्ड सूची के बजाय, इससे दोनों हिस्सों के लिए नामित फ़ील्ड बना सके। कार्ड और उसका लेआउट अभी भी आपके ऐप के कोड में बनाया गया है। स्कीमा केवल उस डेटा का वर्णन करता है जिसे एक journey भरता है।

यह API उन डेवलपर्स के लिए है जो लाइव एक्टिविटीज़ को एकीकृत कर रहे हैं। एक्टिविटीज़ को शुरू करने और अपडेट करने के लिए iOS लाइव एक्टिविटीज़ API देखें।

एक स्कीमा लिखना

attributesType उस स्विफ्ट प्रकार का नाम है जो आपके ऐप में ActivityAttributes के अनुरूप है। Pushwoosh आपके कोड को नहीं पढ़ता है या इसके खिलाफ नाम को मान्य नहीं करता है — यह सिर्फ वह स्ट्रिंग है जिसे API संग्रहीत करता है और वह स्ट्रिंग है जिसे आप startLiveActivity के attributes-type फ़ील्ड में पास करते हैं।

jsonSchema उस प्रकार के दोनों हिस्सों को कवर करता है, दो अलग-अलग जगहों में:

• ContentState फ़ील्ड, यानी वे जो एक्टिविटी के चलने के दौरान बदलते हैं, जैसे कि उड़ान का गेट, स्थिति, या ETA, स्कीमा के रूट properties में जाते हैं।
• ActivityAttributes फ़ील्ड, जो एक्टिविटी के पूरे जीवनकाल के लिए स्थिर होते हैं और शुरू होने पर एक बार सेट होते हैं, जैसे कि उड़ान संख्या, एक अलग attributes सेक्शन में जाते हैं, जिसकी अपनी properties और एक वैकल्पिक required सूची होती है।

attributes सेक्शन वैकल्पिक है। इसके बिना, ActivityAttributes फ़ील्ड लाइव एक्टिविटी एलिमेंट पर नामित फ़ील्ड के बजाय एक फ्री फ़ील्ड नाम/वैल्यू सूची ही रहते हैं। आप वास्तविक attribute वैल्यू हमेशा 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 में ऐसी कोई सूची नहीं है। किसी journey के लिए gate, status, या estimatedTime भरना कभी आवश्यक नहीं है।

एक बार प्रकाशित होने के बाद, एक journey का लाइव एक्टिविटी एलिमेंट इस आकार को पढ़ता है ताकि Card content में gate, status, और estimatedTime के लिए नामित फ़ील्ड की पेशकश की जा सके, बजाय एक रॉ कंटेंट-स्टेट एडिटर के। Card attributes में flightNumber के लिए भी यही होता है, बजाय एक फ्री फ़ील्ड नाम/वैल्यू सूची के।

jsonSchema पर लागू होने वाले प्रारूप और अपरिवर्तनीयता नियमों के लिए नीचे नियम देखें, और सीधे API को कॉल किए बिना समान कार्यों के लिए इस पृष्ठ के अंत में कंट्रोल पैनल में स्कीमा प्रबंधित करना देखें।

बेस URL

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

प्रमाणीकरण

प्रत्येक अनुरोध में आपके सर्वर API टोकन के साथ एक Authorization हेडर शामिल होना चाहिए:

Authorization: Api YOUR_API_TOKEN

नियम

• फ़ील्ड नेमिंग असममित है। अनुरोध lowerCamelCase और प्रोटो नाम दोनों को स्वीकार करते हैं। प्रतिक्रियाएं हमेशा प्रोटो फ़ील्ड नामों के साथ वापस आती हैं, snake_case में (attributes_type, json_schema) — नीचे दिए गए उदाहरण उस केसिंग का उपयोग करते हैं।
• संस्करण अपरिवर्तनीय हैं। एक प्रकाशित संस्करण को संपादित नहीं किया जा सकता है — कोई Update विधि नहीं है। समान attributesType और version के साथ फिर से प्रकाशित करना AlreadyExists के साथ विफल हो जाता है। एक विजेट परिवर्तन हमेशा एक नया संस्करण होता है। उस attributesType के लिए अगला मुफ्त संस्करण प्रकाशित करने के लिए Create पर version को छोड़ दें।
• jsonSchema प्रारूप: एक JSON ऑब्जेक्ट होना चाहिए जिसमें "type": "object" हो, 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	हाँ	वह एप्लिकेशन कोड जिससे स्कीमा संबंधित है।

प्रतिक्रिया

सफलता पर एक खाली ऑब्जेक्ट लौटाता है।

खतरा

इसे पूर्ववत नहीं किया जा सकता है। हटाए गए संस्करण के खिलाफ बनाया गया एक journey का लाइव एक्टिविटी एलिमेंट अपने पहले से सहेजे गए कंटेंट और attribute वैल्यू को रखता है। यह तब से केवल दोनों के लिए फॉर्म संकेतों को खो देता है: कंटेंट एक रॉ JSON एडिटर पर वापस चला जाता है, और attributes एक फ्री फ़ील्ड नाम/वैल्यू सूची पर वापस चले जाते हैं।

त्रुटि प्रतिक्रियाएं

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 ऑन द वायर)।
500 Internal Server Error	अप्रत्याशित सर्वर-साइड विफलता।

कंट्रोल पैनल में स्कीमा प्रबंधित करना

कंट्रोल पैनल API को सीधे कॉल किए बिना समान क्रियाएं प्रदान करता है: प्रकार के अनुसार संस्करणों की सूची बनाएं, एक नया संस्करण प्रकाशित करें, एक संस्करण का JSON देखें, और एक संस्करण हटाएं (एक पुष्टि के साथ, क्योंकि हटाना स्थायी है)। क्लिक पथ के लिए iOS लाइव एक्टिविटी स्कीमा कॉन्फ़िगरेशन देखें।