एक्सटेंशन एपीआई सुविधाएँ

इस पेज का उपयोग तब करें जब आप पहले से ही बेसिक एक्सटेंशन मॉडल को समझते हों और वास्तविक लॉक व्यवहार बनाना चाहते हों: आवश्यक क्रियाएं, अनलॉक अवरोधक, नियमितता, पुरस्कार और दंड।

caution

ब्राउज़र आईफ्रेम कोड विश्वसनीय नहीं है।

आपका iframe यूआई रेंडर कर सकता है और सुरक्षित सेशन कॉन्टेक्स्ट पढ़ सकता है। सेशन स्टेट लिखने, पहनने वाले को इनाम देने, समय हटाने, अनलॉक ब्लॉकर हटाने, विश्वसनीय आवश्यकता की प्रगति रिकॉर्ड करने, प्रयास टाइमर शुरू या विफल करने, या दंड लागू करने वाली किसी भी चीज़ को आपके बैकएंड द्वारा सत्यापित किया जाना चाहिए।

विशेषता मानचित्र

विशेषताएँ	यह क्या करता है	यह कहाँ चलता है
अवरोधकों को अनलॉक करें	जब तक आपका एक्सटेंशन किसी अवरोधक को हटा नहीं देता या पर्याप्त विश्वसनीय प्रगति रिकॉर्ड नहीं कर लेता, तब तक अनलॉक को रोकें	लॉक-स्टार्ट कॉन्फ़िगरेशन या बैकएंड मेटाडेटा/प्रगति कॉल
होम एक्शन	लॉक पेज पर एक दृश्यमान एक्शन जोड़ता है, जैसे "चैलेंज खेलें"	लॉक-स्टार्ट कॉन्फ़िगरेशन या बैकएंड मेटाडेटा पैच
नियमित क्रियाएँ	प्रति अंतराल पहनने वाले की सीमित संख्या में क्रियाओं की अनुमति देता है	Chastify काउंटरों को ट्रैक करता है; आपका बैकएंड विश्वसनीय क्रियाएँ सबमिट करता है
आवश्यक प्रगति	दैनिक या साप्ताहिक पूर्णता आवश्यकताओं को ट्रैक करता है	आपका बैकएंड प्रगति को रिकॉर्ड करता है; Chastify शेड्यूलर छूटी हुई विंडो की जाँच करता है
पुरस्कार	समय हटाता है, स्वच्छता प्रक्रिया शुरू करता है, या सत्यापन सफल होने पर सूचना भेजता है	आपका बैकएंड विशेषाधिकार प्राप्त एंडपॉइंट्स को कॉल करता है
दंड	समय बढ़ाता है, फ्रीज करता है, कार्य सौंपता है, निंदात्मक दंड शुरू करता है, या सत्यापित विफलता के बाद सूचना भेजता है	आपका बैकएंड विशेषाधिकार प्राप्त एंडपॉइंट्स को कॉल करता है

आवश्यक बैकएंड हेडर

विशेषाधिकार प्राप्त एक्सटेंशन एंडपॉइंट्स के लिए दोनों हेडर आवश्यक हैं:

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH

mainToken खुले हुए एक्सटेंशन सेशन की पहचान करता है। डेवलपर API कुंजी यह साबित करती है कि अनुरोध आपके बैकएंड से आया है।

अवरोधकों को अनलॉक करें

अनलॉक ब्लॉकर का उपयोग तब करें जब पहनने वाले को अनलॉक करने से पहले कुछ काम पूरा करना हो। उदाहरण:

• 3 गेम जीतें।
• आज के वर्कआउट का पूरा प्रमाण प्रस्तुत करें।
• एक सत्यापन पहेली को पूरा करें।
• वर्तमान विंडो के लिए सभी आवश्यक एक्सटेंशन क्रियाएं पूरी करें।

दो समर्थित पैटर्न हैं।

प्रगति-आधारित अवरोधक

initialMetadata.unlockRequirements का उपयोग तब करें जब लॉक शुरू होते ही या साझा टेम्पलेट स्वीकार होते ही लॉक को ब्लॉक कर दिया जाना चाहिए। Chastify इस सामान्य कॉन्फ़िगरेशन से एक्सटेंशन सत्र स्थिति को आरंभ करता है, इसलिए उपयोगकर्ता द्वारा आपके एक्सटेंशन को पहली बार खोलने से पहले ही ब्लॉकर मौजूद होता है।

{
  "initialMetadata": {
    "unlockRequirements": [
      {
        "metric": "memory_win",
        "requiredCount": 3,
        "blocker": "Complete 3 memory challenge wins to unlock"
      }
    ],
    "homeActions": [
      {
        "slug": "play-memory-challenge",
        "title": "Play memory challenge",
        "description": "Complete the extension challenge to satisfy the unlock requirement.",
        "icon": "gamepad-2",
        "badge": "Required"
      }
    ]
  }
}

आपके बैकएंड द्वारा विश्वसनीय पूर्णता की पुष्टि हो जाने के बाद, उसी मीट्रिक के लिए प्रगति रिकॉर्ड करें:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/requirements/progress" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "memory_win",
    "amount": 1
  }'

Chastify इसे अनलॉक प्रगति के रूप में संग्रहीत करता है और प्रगति requiredCount तक पहुँचने पर आवश्यकता को स्वतः ही संतुष्ट मान लेता है। लॉक कार्ड 1 of 3 complete जैसी प्रगति दिखा सकते हैं।

स्थिर मीट्रिक नामों का उपयोग करें। एक मीट्रिक उस एक्सटेंशन सत्र के लिए एक सक्रिय अनलॉक आवश्यकता को दर्शाता है।

प्रयास समय सीमा

जब कोई विश्वसनीय प्रयास समय पर पूरा न होने पर समाप्त होना आवश्यक हो, तो attemptLimit का उपयोग करें। Chastify सक्रिय प्रयास को data.attemptLimits.<metric> के अंतर्गत संग्रहीत करता है और समय सीमा समाप्त होने के बाद उसे विफल के रूप में चिह्नित कर सकता है। यह स्थिति Chastify द्वारा प्रबंधित है; data.attemptLimits को स्वयं लिखने के बजाय प्रयास एंडपॉइंट के माध्यम से प्रयासों को प्रारंभ और विफल करें।

{
  "attemptLimit": {
    "enabled": true,
    "metric": "memory_win",
    "durationSeconds": 300,
    "startPolicy": "activity"
  }
}

startPolicy, activity हो सकता है जब पहनने वाला खेलना शुरू करता है और उलटी गिनती शुरू हो जाती है, या availability हो सकता है जब लॉक के लिए कार्रवाई उपलब्ध होते ही उलटी गिनती शुरू हो जाती है।

अपने बैकएंड से एक प्रयास शुरू करें:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/attempts/start" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "memory_win",
    "attemptId": "memory-run-123"
  }'

जब आपका बैकएंड प्रयास की जांच करे, तो Chastify को अनुरोध करें कि यदि समय सीमा बीत चुकी है तो इसे विफल कर दे:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/attempts/fail-expired" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "memory_win",
    "attemptId": "memory-run-123"
  }'

यदि असफल प्रयासों के कारण कूलडाउन स्लॉट का उपयोग होता है, तो असफल प्रयास के लिए एक नियमित कार्रवाई भी प्रस्तुत करें।

मैनुअल अवरोधक

unlockBlockers का उपयोग तब करें जब आपके बैकएंड को मैन्युअल रूप से यह तय करने की आवश्यकता हो कि अनलॉकिंग अवरुद्ध है या नहीं। अपने बैकएंड से मेटाडेटा पैच करें:

curl -X PATCH "https://chastify.net/api/extensions/sessions/$SESSION_ID/metadata" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "unlockBlockers": [
      "Complete 3 memory challenge wins to unlock"
    ],
    "homeActions": [
      {
        "slug": "play-memory-challenge",
        "title": "Play memory challenge",
        "description": "Complete the extension challenge to satisfy the unlock requirement.",
        "icon": "gamepad-2",
        "badge": "Required",
        "intent": {
          "type": "play",
          "title": "Memory challenge",
          "message": "Complete the required challenge."
        }
      }
    ]
  }'

बैकएंड द्वारा पूर्णता सत्यापित होने के बाद ब्लॉकर को हटा दें:

curl -X PATCH "https://chastify.net/api/extensions/sessions/$SESSION_ID/metadata" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "unlockBlockers": [],
    "homeActions": [
      {
        "slug": "play-memory-challenge",
        "title": "Memory challenge complete",
        "description": "The extension unlock requirement has been completed.",
        "icon": "check-circle",
        "badge": "Complete"
      }
    ]
  }'

note

unlockBlockers मैन्युअल मेटाडेटा है। यह Chastify को बताता है कि जब तक आपका बैकएंड ब्लॉकर को नहीं हटाता, तब तक अनलॉकिंग अवरुद्ध है। initialMetadata.unlockRequirements प्रगति-आधारित मेटाडेटा है। Chastify मिलान मेट्रिक के लिए दर्ज की गई विश्वसनीय प्रगति से इसका स्वचालित रूप से मूल्यांकन कर सकता है।

नियमितता विशेषता

नियमित क्रियाएं तब उपयोगी होती हैं जब पहनने वाले को एक निश्चित गति से कुछ करने की अनुमति होती है: प्रति घंटे एक बार, प्रति दिन चार बार, प्रति सप्ताह एक बार, इत्यादि।

आप लॉक एक्सटेंशन बनाते समय नियमित कार्रवाइयों को कॉन्फ़िगर कर सकते हैं, या अपने बैकएंड से चल रहे सत्र को अपडेट कर सकते हैं:

curl -X PATCH "https://chastify.net/api/extensions/sessions/$SESSION_ID/regular-actions/config" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "cumulative",
    "regularitySeconds": 86400,
    "maxActions": 4
  }'

मोड:

• unlimited: क्रियाएँ हमेशा उपलब्ध होती हैं।
• non_cumulative: एक समय में एक ही विंडो उपलब्ध होती है; अप्रयुक्त क्रियाएँ संचित नहीं होती हैं।
• cumulative: क्रियाएँ maxActions तक संचित होती हैं।

वर्तमान उपलब्धता पढ़ें:

curl "https://chastify.net/api/extensions/sessions/$SESSION_ID/regular-actions" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN"

एक विश्वसनीय नियमित कार्रवाई प्रस्तुत करें:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/regular-actions" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "kind": "checkin",
      "score": 92
    }
  }'

नियमित क्रियाओं का उपयोग तब करें जब मुख्य नियम यह हो कि "यह क्रिया कितनी बार हो सकती है?"।

कस्टम आवश्यक क्रियाएँ

जब मुख्य नियम यह हो कि "प्रति दिन या प्रति सप्ताह कितनी पूर्णताएँ आवश्यक हैं?", तो आवश्यक प्रगति का उपयोग करें।

आवश्यकता कॉन्फ़िगरेशन स्थापित एक्सटेंशन सत्र कॉन्फ़िगरेशन में extensionRequirements के अंतर्गत स्थित है:

{
  "extensionRequirements": {
    "enabled": true,
    "metric": "completion",
    "requiredCount": 4,
    "cadence": {
      "every": 1,
      "unit": "day",
      "timezone": "UTC"
    },
    "punishment": {
      "type": "add_time",
      "seconds": 1800,
      "reason": "Daily extension requirement missed"
    }
  }
}

समर्थित कैडेंस इकाइयाँ:

• day
• week

समर्थित छूटी हुई विंडो के लिए दंड के प्रकार:

• none
• add_time
• freeze
• pillory

बैकएंड द्वारा कार्रवाई की पुष्टि हो जाने के बाद ही विश्वसनीय प्रगति रिकॉर्ड करें:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/requirements/progress" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "completion",
    "amount": 1,
    "occurredAt": "2026-05-31T18:42:41.715Z"
  }'

Chastify का शेड्यूलर पूर्ण विंडो का मूल्यांकन करता है और यदि पूर्ण विंडो की संख्या requiredCount से कम है तो कॉन्फ़िगर किए गए छूटी हुई विंडो के दंड को लागू करता है।

tip

आवश्यकता पड़ने पर दोनों सुविधाओं का एक साथ उपयोग करें:

• regular-actions यह सीमित करता है कि कोई पहनने वाला कितनी बार सबमिट कर सकता है।
• requirements/progress यह रिकॉर्ड करता है कि क्या दिन या सप्ताह के लिए पर्याप्त सत्यापित पूर्णताएँ हुई हैं।
• metadata.unlockBlockers ब्लॉक तब तक अनलॉक नहीं होते जब तक वर्तमान आवश्यकता पूरी नहीं हो जाती।

पुरस्कार

रिवॉर्ड्स विशेषाधिकार प्राप्त लॉक क्रियाएं हैं। सत्यापन के बाद सफल होने पर इन्हें अपने बैकएंड से कॉल करें।

समय हटाएँ:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "remove_time",
    "params": 600
  }'

स्वच्छतापूर्ण शुरुआत करें:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hygienic_unlock.start",
    "params": {
      "durationSeconds": 900
    }
  }'

एक अनुकूलित सूचना भेजें:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/notifications/custom" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Challenge complete",
    "message": "Your extension reward was applied.",
    "target": "wearer"
  }'

दंड

दंड भी विशेषाधिकार प्राप्त लॉक क्रियाएं हैं। इन्हें तभी लागू करें जब आपका बैकएंड किसी विफलता या अधूरी आवश्यकता की पुष्टि कर ले।

समय जोड़ें:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "add_time",
    "params": 1800
  }'

जमाना:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "freeze",
    "params": {
      "durationSeconds": 3600
    }
  }'

कार्य सौंपें:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "task.assign",
    "params": {
      "actor": "extension",
      "taskText": "Write a short reflection about the missed requirement.",
      "points": 5,
      "durationMinutes": 30
    }
  }'

सज़ा शुरू करें:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pillory",
    "params": {
      "durationSeconds": 3600,
      "reason": "Extension requirement missed"
    }
  }'

अनुशंसित पैटर्न

खेलों, दिनचर्याओं और सत्यापन चुनौतियों के लिए:

1. आईफ्रेम खुलता है और लॉन्च हैश को पढ़ता है।
2. आईफ्रेम आपके बैकएंड से mainToken का उपयोग करके एक चुनौती बनाने के लिए कहता है।
3. बैकएंड अपने ऐप-स्कोप वाले डेवलपर एपीआई कुंजी के साथ mainToken का आदान-प्रदान/उपयोग करता है।
4. आईफ्रेम आपके बैकएंड को उत्तर भेजता है।
5. बैकएंड परिणाम को सत्यापित करता है।
6. बैकएंड requirements/progress के साथ विश्वसनीय प्रगति रिकॉर्ड करता है।
7. बैकएंड /action के साथ इनाम या दंड लागू करता है।
8. बैकएंड पैच metadata.unlockBlockers और metadata.homeActions।
9. आईफ्रेम सुरक्षित स्थिति/मेटाडेटा को पढ़ता है और परिणाम दिखाता है।

इससे एक्सटेंशन का यूआई रिस्पॉन्सिव बना रहता है और साथ ही सर्वर पर विश्वसनीय लॉक स्थिति भी बरकरार रहती है।