التطبيقات والمفاتيح
عرض التطبيقات
Section titled “عرض التطبيقات”النطاق read:creatives.
curl -s https://api.ad80.dev/v1/apps -H "Authorization: Bearer $AD80_API_KEY"{ "apps": [ { "appId": "com.example.news", "name": "Example News", "createdAt": "2026-10-20T08:00:00Z", "lastUploadAt": "2026-10-28T09:12:44Z", "sdkVersion": "0.2.0", "policyVersion": 3, "creativeCount": 412, "playground": false } ]}القيمة playground: true تميّز تطبيق «جرّب سياستك» الخاص بمؤسستك، فاستبعده من قوائم تطبيقات SDK.
يمثّل lastUploadAt آخر رفع مقبول من SDK (ويكون null قبل أول رفع). وقد يكون sdkVersion
وpolicyVersion بقيمة null.
معلومات تطبيق واحد
Section titled “معلومات تطبيق واحد”النطاق read:creatives. يرجع تطبيقًا واحدًا بالشكل نفسه. استعلم عنه بشكل متكرر لتنتظر أول رفع (lastUploadAt).
يرد بالرمز 404 إن لم يكن التطبيق موجودًا في مؤسستك.
إنشاء تطبيق
Section titled “إنشاء تطبيق”النطاق manage:keys.
curl -s -X POST https://api.ad80.dev/v1/apps \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{"appId": "com.example.news", "name": "Example News"}'| الحقل | الشروط |
|---|---|
appId | مطلوب. معرّف التطبيق: معرّف تطبيق Android، أو معرّف الحزمة (bundle identifier) في iOS الذي يرسله SDK. مقطعان على الأقل تفصل بينهما نقاط، يبدأ كل مقطع بحرف، ثم حروف أو أرقام أو _. حتى 150 حرفًا. لا تُقبل الشرطة (-)، فمعرّف الحزمة الذي يحتوي شرطة (وتسمح بها Apple) يُرفض حالياً بالرمز 400. |
name | اسم للعرض، اختياري، حتى 100 حرف. |
يرد بالرمز 201 ومعه التطبيق. ويرد بالرمز 409 إن كان معرّف التطبيق موجودًا من قبل في مؤسستك.
عرض المفاتيح
Section titled “عرض المفاتيح”النطاق manage:keys. يعرض مفاتيح الرفع (ingest) ومفاتيح API (client). لا يرجع المفاتيح السرية أبدًا،
بل prefix فقط، وهو جزء غير سري (أول 12 حرفًا).
{ "keys": [ { "id": "ik_7", "type": "ingest", "prefix": "ad80_ik_Ab3x", "label": "Release build", "appId": "com.example.news", "createdBy": "user:31", "createdAt": "2026-10-20T08:01:00Z", "lastUsedAt": "2026-10-28T09:12:44Z", "expiresAt": null, "revokedAt": null }, { "id": "ck_3", "type": "client", "prefix": "ad80_ck_Q9zL", "label": "Nightly export", "scopes": ["read:creatives", "read:verdicts"], "createdBy": "user:31", "createdAt": "2026-10-21T10:00:00Z", "lastUsedAt": null, "expiresAt": "2027-10-21T10:00:00Z", "revokedAt": null, "rotatedFrom": "ck_1" } ]}يُحدَّث lastUsedAt مرة واحدة في الدقيقة على الأكثر.
إنشاء مفتاح أو تجديده
Section titled “إنشاء مفتاح أو تجديده”النطاق manage:keys.
| الحقل | معناه |
|---|---|
type | client (الافتراضي) أو ingest. |
label | اختياري، حتى 100 حرف. |
scopes | لمفاتيح API: نطاق واحد على الأقل. لا يمنح المفتاح إلا نطاقات يملكها هو نفسه (وإلا فالرد 403). |
appId | لمفاتيح الرفع: التطبيق الذي يرفع المفتاح باسمه (مطلوب إلا عند التجديد). |
expiresInDays | اختياري، من 0 إلى 3650. القيمة 0 أو غياب الحقل: بلا انتهاء. |
rotates | اختياري: معرّف مفتاح نشط تريد استبداله، مثل ik_7 أو ck_3. يأخذ المفتاح الجديد نطاقات المفتاح القديم أو تطبيقه. |
graceHours | مع rotates: تنتهي صلاحية المفتاح القديم بعد هذا العدد من الساعات (من 0 إلى 8760). القيمة 0 أو غياب الحقل: يبقى المفتاح القديم صالحًا حتى تبطله بنفسك. |
إنشاء مفتاح رفع لتطبيق:
curl -s -X POST https://api.ad80.dev/v1/keys \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{"type": "ingest", "appId": "com.example.news", "label": "Release build"}'إنشاء مفتاح API للقراءة فقط تنتهي صلاحيته بعد سنة:
curl -s -X POST https://api.ad80.dev/v1/keys \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{"type": "client", "label": "BI export", "scopes": ["read:creatives", "read:verdicts"], "expiresInDays": 365}'تجديد مفتاح رفع، مع إبقاء القديم صالحًا 30 يومًا ريثما يصل تحديث التطبيق إلى المستخدمين:
curl -s -X POST https://api.ad80.dev/v1/keys \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{"rotates": "ik_7", "graceHours": 720}'الرد 201. الحقل key هو المفتاح السري، ولن تراه إلا هنا:
{ "id": "ik_8", "key": "ad80_ik_THE_NEW_SECRET", "prefix": "ad80_ik_Zx81", "expiresAt": null, "note": "the key is shown once; store it now"}مفاتيح API ترجع معها scopes أيضًا. وإن حاولت إنشاء مفتاح رفع على باقة لا تشمل الربط مع SDK، يكون
الرد 403 مع entitlement: sdk_ingest.
إبطال مفتاح
Section titled “إبطال مفتاح”النطاق manage:keys. قيمة id هي ck_<n> أو ik_<n>. يتوقف المفتاح عن العمل فورًا.
curl -s -X POST https://api.ad80.dev/v1/keys/ik_7/revoke -H "Authorization: Bearer $AD80_API_KEY"{ "id": "ik_7", "revoked": true }في حالات نادرة يضيف الرد الحقل warning، وعندها يسري الإبطال خلال 30 ثانية.