Landing Pages API

Μια σελίδα προορισμού είναι μια δημόσια σελίδα που η ομάδα σας χτίζει στον επεξεργαστή του Joryio (drag & drop ή HTML), δημοσιεύει σε μια διεύθυνση και, προαιρετικά, της βάζει μια φόρμα. Μια υποβληθείσα φόρμα ταυτοποιεί το άτομο, γράφει χαρακτηριστικά και εγγραφές σε λίστες στο προφίλ του και καταγράφει τα συμβάντα Landing Page Viewed και Landing Page Form Submitted, που τμήματα, χοάνες, journeys και καμπάνιες με έναυσμα μπορούν να χρησιμοποιήσουν όπως κάθε άλλο συμβάν.

Όλα τα endpoints αυτής της σελίδας είναι σχετικά με τη βασική διεύθυνση: https://api-eu1.joryio.com/api - δείτε Επισκόπηση API.

Δικαιώματα: landing_pages:read, landing_pages:write, landing_pages:publish (δείτε Κλειδιά API).

Πού ζει μια σελίδα

Μια δημοσιευμένη σελίδα εξυπηρετείται στο <pages host>/<workspace handle>/<slug>. Το handle του χώρου εργασίας είναι το δικό του id - αδιαφανές, μόνιμο, ποτέ επιλεγμένο ή μετονομασμένο (https://<workspace id>.eu1.jrypages.com/<slug> στον τομέα σελίδων)· το slug είναι μοναδικό ανά χώρο εργασίας και προκύπτει από το όνομα της σελίδας εκτός αν το ορίσετε. Ένας χώρος εργασίας μπορεί αντ' αυτού να εξυπηρετεί τις σελίδες του σε δικό του υποτομέα (https://pages.yourbrand.com/<slug>) - δείτε Χρήση δικού σας τομέα. Κάθε σελίδα έχει επίσης έναν σύνδεσμο προεπισκόπησης (?preview=<signature>, από το previewUrl): το τρέχον πρόχειρο, ορατό χωρίς είσοδο στο Joryio σε όποιον έχει τον σύνδεσμο, ποτέ σε cache και ποτέ ευρετηριασμένο· παύει να λειτουργεί όταν η σελίδα αποσυρθεί.

Το σχήμα της φόρμας

Το 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	το email / τηλέφωνο της επαφής	το πολύ ένα από κάθε είδος· phone με lists εγγράφει σε αυτές τις λίστες
text, number, date, dropdown, radio	το χαρακτηριστικό που ονομάζει το attribute (προεπιλογή: το κλειδί)	dropdown και radio χρειάζονται options· το radio είναι πάντα υποχρεωτικό
checkbox	ένα boolean χαρακτηριστικό· με 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). Μια φόρμα χρειάζεται πεδίο email ή τηλεφώνου ώστε να ταυτοποιείται το άτομο· ένας σύνδεσμος από μήνυμα του Joryio θα μπορεί να φέρει διακριτικό ατόμου αντί αυτού (σχεδιάζεται).

Endpoints

Μέθοδος	Διαδρομή	Δικαίωμα	Τι κάνει
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 blocker ή recommendation, scope, params). Τα blockers σταματούν τη δημοσίευση· το POST .../publish απαντά 400 με τα ίδια ευρήματα
GET	/landing-pages/handle	landing_pages:read	Η διεύθυνση σελίδων του χώρου εργασίας: { handle, host, example, customHost }. Το handle είναι το id του ίδιου του χώρου εργασίας, η πρώτη ετικέτα κάθε διεύθυνσης σελίδας - αδιαφανές, μόνιμο, ποτέ επιλεγμένο ή μετονομασμένο· το 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 και του πιστοποιητικού στο edge· απαντά τον τομέα με την τρέχουσα κατάστασή του
DELETE	/landing-pages/domain/:id	landing_pages:publish	Αφαίρεση του τομέα· οι διευθύνσεις σελίδων επιστρέφουν αμέσως στον τομέα σελίδων
GET	/landing-pages/capabilities	landing_pages:read	{ botCheck }: αν ο διακομιστής μπορεί να επαληθεύσει Cloudflare Turnstile, ώστε μια φόρμα να ορίσει botCheck: true

Δημόσιες διαδρομές (χωρίς πιστοποίηση)

Μέθοδος	Διαδρομή	Τι κάνει
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	Ο σύνδεσμος σε email διπλής επιβεβαίωσης: εγγράφει στις λίστες που ονομάζει το διακριτικό και δείχνει σελίδα επιβεβαίωσης

Τα όρια ρυθμού ορίζονται από το ποιος κάνει το αίτημα, όχι από τη διεύθυνση IP - ένας πάροχος κινητής ή ένα γραφείο μπορεί να βάλει χιλιάδες ανθρώπους πίσω από μία διεύθυνση. Η σελίδα, το beacon προβολής της και το /p/go έχουν μόνο ένα ανώτατο όριο πλημμύρας 30.000 αιτημάτων ανά λεπτό ανά IP. Ένας έγκυρος σύνδεσμος επιβεβαίωσης δεν περιορίζεται ποτέ· οι μη έγκυροι απορρίπτονται μετά από 300 ανά λεπτό από το ίδιο IP. Υποβολές φορμών: 15 ανά λεπτό και 60 ανά ώρα από το ίδιο άτομο (email, αλλιώς τηλέφωνο) στην ίδια φόρμα, 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 τον καταχωρεί στο edge και απαντά με τον τομέα σε κατάσταση 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 με μήνυμα που το κατονομάζει. Ζητήστε μας να αυξήσουμε το όριο για περισσότερους χώρους εργασίας ή επωνυμίες.

Συγκατάθεση: διπλή επιβεβαίωση και έλεγχος bot

Μια λίστα που απαιτεί διπλή επιβεβαίωση (ρυθμίσεις λίστας) δεν εγγράφεται ποτέ απευθείας από φόρμα. Το άτομο γράφεται και το συμβάν καταγράφεται, η απάντηση λέει να ελέγξει τα εισερχόμενα, και ένα email (στη γλώσσα της σελίδας, μέσω της ρύθμισης email του χώρου εργασίας) φέρει υπογεγραμμένο σύνδεσμο που ισχύει επτά ημέρες· το GET /p/confirm/:token εγγράφει τις λίστες με optInSource: double_opt_in και δείχνει σελίδα επιβεβαίωσης. Η γραμμή μητρώου τις παραθέτει στο listsPending· ο έλεγχος πριν τη δημοσίευση λέει ποιες λίστες θα ζητήσουν επιβεβαίωση.

Το form.botCheck: true αποδίδει ένα widget 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 παραθέτει τα πρότυπα του χώρου εργασίας και πέντε ενσωματωμένα (εγγραφή σε newsletter, εγγραφή σε εκδήλωση, λίστα αναμονής προϊόντος, κλήρωση, σύντομα κοντά σας). Ένα ενσωματωμένο έχει σταθερό id· το 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 } - το μοντέλο σχεδιάζει τις ενότητες και γράφει το κείμενο, ντετερμινιστικός κώδικας χτίζει τη σήμανση πάνω στο Brand Kit, και τίποτα δεν αποθηκεύεται μέχρι να αποθηκεύσετε. Το POST /ai/pages/revise με source (το HTML της σελίδας) και instruction επιστρέφει { source, reply }, ολόκληρο το αναθεωρημένο έγγραφο· μια αναθεώρηση που αφαιρεί τη φόρμα ή προσθέτει script απορρίπτεται.

Σύνδεσμος σε σελίδα από μήνυμα. Σε οποιοδήποτε σώμα email, SMS ή WhatsApp, το {{ 'spring-sale' | landing_page_url }} αποδίδει σύνδεσμο προς τη δημοσιευμένη σελίδα με αυτό το slug. Ο σύνδεσμος φέρει το διακριτικό του παραλήπτη (?jp=), ώστε η προβολή και η υποβολή της φόρμας να γράφονται σε αυτό το άτομο πριν καν πληκτρολογήσει email· ένα δεύτερο όρισμα προσθέτει συμβολοσειρά ερωτήματος: {{ 'spring-sale' | landing_page_url: 'utm_campaign=spring' }}. Ένα μη δημοσιευμένο slug αποδίδει κενή συμβολοσειρά.

Συμβάντα. Τα Landing Page Viewed και Landing Page Form Submitted εμφανίζονται σε κάθε επιλογέα συμβάντων (εναύσματα journeys, καμπάνιες με έναυσμα, τμήματα) κάτω από τα συμβάντα πλατφόρμας, με τις ιδιότητές τους.

Τι κάνει μια υποβολή

1. Επικυρώνει τις τιμές έναντι του σχήματος· τα άγνωστα πεδία αγνοούνται, τα σφάλματα επιστρέφουν ως { "ok": false, "errors": [...] }.
2. Ταυτοποιεί το άτομο: ένα υπάρχον προφίλ με το ίδιο email ενημερώνεται, αλλιώς δημιουργείται προφίλ με παραγόμενο εξωτερικό id και source landing_page:<slug>. Ένα email ή τηλέφωνο συμπληρώνεται μόνο όταν το προφίλ δεν έχει· ένα άτομο που κατονομάζεται από το token του συνδέσμου (jp) μπορεί να ενημερώσει το δικό του τηλέφωνο, ποτέ το email του.
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://..." }.

Δείτε επίσης: Σελίδες προορισμού & φόρμες στον οδηγό χρήστη - η ίδια δυνατότητα από την πλευρά του marketer.