Landing Pages API

דף נחיתה הוא דף ציבורי שהצוות שלכם בונה בעורך של Joryio (Drag & drop או HTML), מפרסם לכתובת, ואפשר להוסיף לו טופס. טופס שנשלח מזהה את האדם, כותב מאפיינים ורישומים לרשימות תפוצה לפרופיל שלו, ורושם את האירועים Landing Page Viewed ו-Landing Page Form Submitted, שסגמנטים, משפכים, מסעות וקמפיינים מופעלים יכולים להשתמש בהם כמו בכל אירוע אחר.

כל נקודות הקצה בדף זה יחסיות לכתובת הבסיס: https://api-eu1.joryio.com/api - ראו סקירת API.

הרשאות: landing_pages:read, landing_pages:write, landing_pages:publish (ראו מפתחות API).

איפה הדף חי

דף מפורסם מוגש בכתובת <pages host>/<workspace handle>/<slug>. ה-handle של סביבת העבודה הוא המזהה שלה עצמו - אטום, קבוע, לעולם לא נבחר ולא משתנה (https://<workspace id>.eu1.jrypages.com/<slug> בדומיין הדפים); ה-slug ייחודי לסביבת העבודה ונגזר משם הדף אלא אם הגדרתם אותו. סביבת עבודה יכולה להגיש את הדפים שלה בתת-דומיין משלה במקום (https://pages.yourbrand.com/<slug>) - ראו שימוש בדומיין משלכם. לכל דף יש גם קישור תצוגה מקדימה (?preview=<signature>, מתוך previewUrl): הטיוטה הנוכחית, שכל מי שמחזיק בקישור יכול לראות בלי כניסה ל-Joryio, לעולם לא נשמרת במטמון ולא מאונדקסת; הקישור מפסיק לעבוד כשהדף מוסר מפרסום.

סכמת הטופס

form הוא מה שנתיב השליחה הציבורי מאמת מולו. סימון הדף נושא רק את שמות השדות.

{
  "fields": [
    { "key": "email", "type": "email", "label": "Email", "required": true },
    { "key": "first_name", "type": "text", "label": "First name", "attribute": "firstName" },
    { "key": "size", "type": "radio", "options": [{ "label": "S", "value": "s" }, { "label": "M", "value": "m" }] },
    { "key": "marketing", "type": "checkbox", "label": "Email me offers", "lists": ["<listId>"] },
    { "key": "lists", "type": "subscriptions", "lists": ["<listId>", "<listId>"] },
    { "key": "src", "type": "hidden", "value": "utm_source" }
  ],
  "submit": { "action": "message", "message": "Thanks - check your inbox." },
  "identity": "email"
}

סוג	כותב	הערות
email, phone	האימייל / הטלפון של איש הקשר	לכל היותר אחד מכל סוג; phone עם lists רושם לרשימות אלה
text, number, date, dropdown, radio	המאפיין ששמו ב-attribute (ברירת מחדל: המפתח)	dropdown ו-radio דורשים options; radio תמיד חובה
checkbox	מאפיין בוליאני; עם lists, רושם כשמסומן	תיבות הסכמה לעולם לא מסומנות מראש
checkbox_group	מאפיין מערך	options חובה
subscriptions	רושם לרשימות שסומנו	lists חובה
hidden	מאפיין מ-value קבוע, או utm_source, utm_medium, utm_campaign, utm_content, utm_term, referrer, page

submit.eventName (אופציונלי) מפעיל את האירוע המותאם הזה על האדם בנוסף לאירוע הפלטפורמה, עם הערכים שנשלחו כמאפיינים; submit.setAttributes (אופציונלי, { "lead_source": "spring_sale" }) כותב ערכי מאפיינים קבועים בכל שליחה. את שניהם אפשר להגדיר גם על כפתור השליחה בעורך. submit.action הוא message (הצגת message במקום) או redirect (ל-url, https בלבד). טופס צריך שדה אימייל או טלפון כדי שאפשר יהיה לזהות את האדם; קישור מהודעת Joryio יוכל לשאת אסימון אדם במקום (מתוכנן).

נקודות קצה

Method	Path	הרשאה	מה זה עושה
GET	/landing-pages	landing_pages:read	רשימה מעומדת ({ data, pagination }) עם סטטוס, סטטיסטיקה, מי יצר ומי ערך לאחרונה, וכתובת ציבורית. ?templates=true מציג תבניות (שלכם ואז המובנות); סינון ?status= (מופרד בפסיקים), ?q=, ?tags=, ?createdBy=, ?editedBy=; סידור על כל הרשימה עם ?sortBy= (name, status, views, submissions, createdAt, editedAt, publishedAt) ו-?sortOrder=; ?limit= (עד 100), ?offset=
GET	/landing-pages/:id/history	landing_pages:read	היסטוריית ביקורת של דף אחד, מהחדש לישן: יצירה, עדכון, פרסום, הורדה ומחיקה עם המבצע. ?limit= 1-200
POST	/landing-pages	landing_pages:write	יצירת טיוטה: name, slug, mode (dnd או html), html, css, grapejsData, form, seo (title, description, faviconUrl, ogImageUrl, noIndex), language, dir, tags, sdkEnabled, personalized
GET	/landing-pages/:id	landing_pages:read	דף אחד במלואו, עם publicUrl ו-previewUrl
PUT	/landing-pages/:id	landing_pages:write	עדכון; הדף החי משתנה רק בפרסום הבא
DELETE	/landing-pages/:id	landing_pages:write	מחיקת טיוטה (הסירו מפרסום קודם)
POST	/landing-pages/:id/duplicate	landing_pages:write	העתקת דף או יצירת דף מתבנית; { "asTemplate": true } שומר את ההעתק כתבנית
POST	/landing-pages/:id/publish	landing_pages:publish	הקפאת המסמך המסונן והגשתו
POST	/landing-pages/:id/unpublish	landing_pages:publish	הסרה; אסימון החתימה מתחלף
GET	/landing-pages/:id/preview	landing_pages:read	הטיוטה מעובדת כמו הדף החי (HTML); השליחות ממנה נזרקות
GET	/landing-pages/:id/submissions	landing_pages:read	יומן השליחות, מהחדש לישן; מידע אישי מוסתר בלי pii:view. ?limit= (עד 200), ?before=
GET	/landing-pages/:id/submissions.csv	landing_pages:read	כל השליחות כ-CSV מוזרם, מהישן לחדש: submitted_at, עמודה לכל שדה בטופס (כל תשובה, ממופה או לא), person_id, identified_by, lists_subscribed, referrer וערכי utm_*; מידע אישי מוסתר בלי pii:view
GET	/landing-pages/:id/report	landing_pages:read	צפיות, צפיות ראשונות ושליחות לפי יום (UTC), סיכומים ושיעור המרה לטווח, ומוני כל הזמנים. ?days= 1-365 (ברירת מחדל 30)
GET	/landing-pages/:id/review	landing_pages:read	סקירת השקה: ממצאים (code, severity חוסם או המלצה, scope, params). חוסמים מונעים פרסום; POST .../publish עונה 400 עם אותם ממצאים
GET	/landing-pages/handle	landing_pages:read	כתובת הדפים של סביבת העבודה: { handle, host, example, customHost }. ה-handle הוא מזהה סביבת העבודה עצמו, התווית הראשונה בכל כתובת דף - אטום, קבוע, לעולם לא נבחר ולא משתנה; customHost הוא הדומיין הפעיל של סביבת העבודה עצמה, כשיש לה כזה
GET	/landing-pages/domain	landing_pages:publish	הדומיין של סביבת העבודה: { domain, limit, used, pagesHost } - domain (או null) עם id, hostname, status (pending, active, failed), verifiedAt, target, records (רשומות ה-DNS להוספה), providerConfigured, lastError; limit ו-used סופרים את דומייני דפי הנחיתה של הארגון
POST	/landing-pages/domain	landing_pages:publish	הוספת דומיין משלכם: { "hostname": "pages.yourbrand.com" }. מחזיר את הדומיין במצב pending עם רשומות ה-DNS שלו. 409 כשלסביבת העבודה כבר יש דומיין או כשהארגון הגיע למגבלה (ההודעה נוקבת במגבלה)
POST	/landing-pages/domain/:id/verify	landing_pages:publish	בדיקה חוזרת של ה-DNS והתעודה בקצה; מחזיר את הדומיין עם מצבו הנוכחי
DELETE	/landing-pages/domain/:id	landing_pages:publish	הסרת הדומיין; כתובות הדפים חוזרות מיד לדומיין הדפים
GET	/landing-pages/capabilities	landing_pages:read	{ botCheck }: האם השרת יכול לאמת Cloudflare Turnstile, כך שטופס יכול להגדיר botCheck: true

נתיבים ציבוריים (ללא אימות)

Method	Path	מה זה עושה
GET	/p/:handle/:slug	הדף המפורסם
POST	/p/:id/view	אות צפייה שהדף עצמו שולח
POST	/p/:id/submit	שליחת טופס; הגוף נושא את החתימה שהמסמך המפורסם מטמיע, כך שרק הדף כפי שפורסם יכול לשלוח
GET	/p/go/:workspaceId/:slug	לאן מצביע {{ 'slug' | landing_page_url }} בהודעה: הפניה (302) לכתובת הקנונית של הדף, עם מחרוזת השאילתה (טוקן האדם, ערכי UTM)
GET	/p/confirm/:token	הקישור במייל אישור כפול: מרשים לרשימות שהטוקן מציין ומציג דף אישור

מגבלות הקצב נקבעות לפי מי שפונה, לא לפי כתובת IP - ספק סלולר או משרד יכולים להציב אלפי אנשים מאחורי כתובת אחת. לדף, ל-beacon הצפייה שלו ול-/p/go יש רק תקרת הצפה של 30,000 בקשות לדקה לכל IP. קישור אישור תקף לעולם אינו מוגבל; קישורים לא תקפים נדחים אחרי 300 לדקה מאותו IP. שליחות טפסים: 15 לדקה ו-60 לשעה מאותו אדם (אימייל, אחרת טלפון) באותו טופס, 3,000 לדקה לכל דף, ו-2,000 לדקה לכל IP; שליחה שנדחתה מציגה הודעה בשפת הדף. גוף דף מוגבל ל-500 KB ו-50 שדות. כל טופס נושא שדה honeypot ושהייה מינימלית של שתי שניות.

שימוש בדומיין משלכם

במקום https://<workspace id>.eu1.jrypages.com/<slug>, סביבת עבודה יכולה להגיש את הדפים שלה בתת-דומיין שבבעלותה - https://pages.yourbrand.com/<slug>. הדומיין מוגדר מהגדרות -> דפי נחיתה (הכרטיס "הדומיין שלכם") או בארבעת הנתיבים שלמעלה; נדרשת ההרשאה landing_pages:publish.

1. הוסיפו את תת-הדומיין (POST /landing-pages/domain). תת-דומיין שבבעלותכם, כמו pages.yourbrand.com - לא דומיין שורש, ולעולם לא דומיין של Joryio. Joryio רושמת אותו בקצה ומחזירה את הדומיין במצב pending עם רשומות ה-DNS להגדרה.
2. הוסיפו את רשומות ה-DNS אצל ספק ה-DNS שלכם: רשומת CNAME מתת-הדומיין אל היעד ש-Joryio נותנת לכם, ורשומות אימות התעודה (TXT). הגדרות -> דפי נחיתה מציגים אותן עם כפתור העתקה; records נושא את אותה רשימה.
3. אמתו (POST /landing-pages/domain/:id/verify). ברגע שה-CNAME נפתר, התעודה מונפקת תוך כמה דקות והמצב הופך ל-active; דומיינים ממתינים נבדקים גם מעצמם כל חמש דקות. אימות שפג תוקפו הופך ל-failed, עם הסיבה ב-lastError - תקנו את הרשומות ואמתו שוב, או הסירו את הדומיין והוסיפו אותו מחדש.

כל עוד הדומיין active, כל כתובת דף ש-Joryio כותבת - ה-publicUrl של דף, קישור התצוגה המקדימה, {{ 'slug' | landing_page_url }} בהודעות וההפניה /p/go שמאחוריו - משתמשת בו; כתובת הדפים ממשיכה להגיש את אותם דפים, כך ששום דבר לא נשבר לפני או אחרי. הסרת הדומיין (DELETE /landing-pages/domain/:id) מחזירה את הכתובות מיד לכתובת הדפים; הדפים נשארים מפורסמים.

כמה. לסביבת עבודה יש לכל היותר דומיין אחד. לארגון מותר כברירת מחדל דומיין דפי נחיתה אחד על פני כל סביבות העבודה שלו; GET /landing-pages/domain מדווח על ה-limit וכמה used, והוספה מעבר למגבלה מחזירה 409 עם הודעה שנוקבת בה. בקשו מאיתנו להעלות את המגבלה לסביבות עבודה או מותגים נוספים.

הסכמה: אישור כפול ובדיקת בוט

רשימה שדורשת אישור כפול (הגדרות הרשימה) לעולם לא נרשמת ישירות מטופס. האדם נכתב והאירוע נרשם, התשובה אומרת לבדוק את תיבת הדואר, ומייל אחד (בשפת הדף, דרך הגדרות האימייל של סביבת העבודה) נושא קישור חתום התקף שבעה ימים; GET /p/confirm/:token מרשים לרשימות עם optInSource: double_opt_in ומציג דף אישור. שורת היומן מציגה אותן תחת listsPending; סקירת ההשקה אומרת אילו רשימות יבקשו אישור.

form.botCheck: true מציג ווידג'ט Cloudflare Turnstile לפני כפתור השליחה ודוחה שליחה שהטוקן שלה אינו מאומת. זמין רק כשהשרת מוגדר ל-Turnstile (GET /landing-pages/capabilities). טפסים בתוך הודעות באפליקציה לא זקוקים לזה: ה-SDK מאמת אותם.

מבקרים, ה-Web SDK והתאמה אישית

דף מפורסם סופר בעצמו צפיות, צפיות ראשונות ושליחות; מבקר שמגיע דרך קישור מהודעה הנושא את הטוקן שלו (?jp=, ראו את פילטר ה-Liquid למטה) מקבל Landing Page Viewed בפרופיל. שני מתגים לכל דף מרחיבים זאת:

• sdkEnabled טוען את ה-Web SDK של סביבת העבודה בדף החי (דורש אפליקציית Web פעילה תחת הגדרות > אפליקציות, אחרת השמירה נדחית). כל מבקר מקבל סשן ואירועים כמו בכל דף עם ה-SDK; זמן הריצה מתעד Landing Page Viewed דרך ה-SDK, מבקר עם טוקן מזוהה בהגעה, וטופס שנשלח מזהה את המבקר כאדם שאליו נכתב, כך שההיסטוריה האנונימית שלו מתמזגת לפרופיל. הודעות בתוך האפליקציה המכוונות לאפליקציית ה-Web יכולות להופיע בדף. תצוגה מקדימה בעורך לעולם לא טוענת את ה-SDK.
• personalized מרנדר את ה-Liquid של הדף למבקר שמגיע עם טוקן, כמו בהודעה ({{ user.firstName | default: "there" }}, מאפיינים, landing_page_url); בלי טוקן אותו דף מרונדר עם אדם ריק, כך שברירות המחדל מוצגות. רינדור אישי מוגש עם Cache-Control: private, no-store; פילטר catalog אינו זמין בדפים.

תבניות, AI וקישורים מהודעות

תבניות מובנות. ?templates=true מחזיר את התבניות של סביבת העבודה וחמש תבניות מובנות (הרשמה לניוזלטר, רישום לאירוע, רשימת המתנה למוצר, הגרלה, בקרוב). לתבנית מובנית מזהה קבוע; POST /landing-pages/:id/duplicate עליה יוצר דף רגיל בסביבת העבודה. כל דף הופך לתבנית עם { "asTemplate": true }.

עיצוב ועריכה ב-AI (מהדשבורד בלבד, landing_pages:write): POST /ai/pages/design עם brief, ואופציונלית language, brandVoiceId, archetype (bold, editorial, minimal, product, event), colorStrategy (restrained, committed, drenched), goal (signup, waitlist, event, download, contest, other) מחזיר { name, seo, design, html, css, form, language, dir } - המודל מתכנן את המקטעים וכותב את הטקסט, קוד דטרמיניסטי בונה את ה-HTML על ערכת המותג, ודבר לא נשמר עד שתשמרו. POST /ai/pages/revise עם source (ה-HTML של הדף) ו-instruction מחזיר { source, reply }, את המסמך המעודכן כולו; עריכה שמוחקת את הטופס או מוסיפה סקריפט נדחית.

קישור לדף מתוך הודעה. בכל גוף אימייל, SMS או WhatsApp, {{ 'spring-sale' | landing_page_url }} מייצר קישור לדף המפורסם עם ה-slug הזה. הקישור נושא את הטוקן של הנמען (?jp=), כך שהצפייה ושליחת הטופס נכתבות לאותו אדם עוד לפני שהקליד אימייל; ארגומנט שני מוסיף מחרוזת שאילתה: {{ 'spring-sale' | landing_page_url: 'utm_campaign=spring' }}. slug שלא פורסם מייצר מחרוזת ריקה.

אירועים. Landing Page Viewed ו-Landing Page Form Submitted מופיעים בכל בורר אירועים (טריגרים של מסעות, קמפיינים מופעלים, סגמנטים) תחת אירועי הפלטפורמה, עם המאפיינים שלהם.

מה שליחה עושה

1. מאמתת את הערכים מול הסכמה; שדות לא מוכרים מתעלמים מהם, שגיאות חוזרות כ-{ "ok": false, "errors": [...] }.
2. מזהה את האדם: פרופיל קיים עם אותו אימייל מתעדכן, אחרת נוצר פרופיל עם מזהה חיצוני מחולל ו-source בערך landing_page:<slug>. אימייל או טלפון ממולאים רק כשאין לפרופיל כאלה; אדם שמזוהה על ידי הטוקן של הקישור (jp) יכול לעדכן את הטלפון שלו, אבל אף פעם לא את האימייל.
3. כותבת את המאפיינים הממופים, רושמת לרשימות שסומנו, ורושמת Landing Page Form Submitted עם pageId, pageSlug, pageName, מפתחות השדות, listsSubscribed, referrer, ערכי ה-UTM, וה-email וה-phone של הטופס עם phoneUpdated (true כשהפרופיל מחזיק עכשיו בטלפון של הטופס, false כשהוא שמר טלפון אחר; לא קיים כשבטופס לא היה טלפון או שהיה אותו טלפון).
4. שומרת שורת יומן (לשונית השליחות) ומגדילה את מונה ה-submissions של הדף.
5. עונה { "ok": true, "message": "..." } או { "ok": true, "redirect": "https://..." }.

ראו גם: דפי נחיתה וטפסים במדריך למשתמש - אותה יכולת מצד המשווק.