diff --git a/docs/photoniq/event-delivery/clients/connect-to-stream.md b/docs/photoniq/event-delivery/clients/connect-to-stream.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/photoniq/event-delivery/clients/index.md b/docs/photoniq/event-delivery/clients/index.md index 17523e9a79..bb95804197 100644 --- a/docs/photoniq/event-delivery/clients/index.md +++ b/docs/photoniq/event-delivery/clients/index.md @@ -1,23 +1,33 @@ --- sidebar_position: 1 -title: Event Delivery Client SDKs +title: Getting Started with Event Delivery Client SDKs --- -This section demonstrates some of the tasks you can complete with JavaScript SDKs. Macrometa offers the following SDKs: - +PhotonIQ offers two client SDKs to enable you connect to and deliver event streams to your applications, services, and several other data-volatile use cases. These SDKs are written in Javascript: - [WebSocket](/download/eds-clients/photoniq-eds-ws.min.js) -- SSE (coming soon) +- Server Sent Events (SSE) + This section demonstrates some simple tasks to help get you started using these client SDKs. -## Pre-requisites +## Objectives +In event delivery, an event refers to every new data generated or function executed. Getting started with this PhotonIQ service will involve you connecting to and subscribing to events from a stream. + +This quickstart guide will guide you through: +- Connecting to an event delivery service +- Querying that service and receiving query results +- Disconnecting from the event delivery service -- Download `photoniq-eds-ws.min.js` or `photoniq-eds-sse.min.js` from section above. -- Attach the module to your html: + +## Pre-requisites +You need the WebSocket or SSE client to successfully complete this guide: +1. Download the `photoniq-eds-ws.min.js` or `photoniq-eds-sse.min.js` client SDK. +1. Attach the Javascript module to html code ```html ``` + ## Basic Example Connect to Event Delivery Service, retrieve and subsribe to SQL: diff --git a/docs/photoniq/event-delivery/event-delivery-queries.md b/docs/photoniq/event-delivery/event-delivery-queries.md index 2e83997cfb..bffc0f7127 100644 --- a/docs/photoniq/event-delivery/event-delivery-queries.md +++ b/docs/photoniq/event-delivery/event-delivery-queries.md @@ -1,16 +1,16 @@ --- sidebar_position: 60 -title: Event Delivery Queries +title: Event Delivery Filters --- -PhotonIQ Event Delivery offers powerful filtering capabilities that allow users to specify exactly which events they want to receive. By using PostgreSQL SELECT statement syntax, users can define filters to tailor the event stream to their needs. This page outlines how to construct these queries, providing syntax guidelines, use cases, and examples. +PhotonIQ Event Delivery offers powerful filtering capabilities that allow users to specify exactly which events they want to receive. By using the PostgreSQL `SELECT` statement syntax, users can define filters to tailor the event stream to their needs. This page outlines how to construct these queries, providing syntax guidelines, use cases, and examples. ## Syntax Filters are defined in a JSON format string, which includes fields to specify the desired event criteria. The fundamental structure of a filter includes: - `action`: Defines the filter action, such as "add" for adding new filters or "remove" for removing existing filters. -- `once`: A boolean flag (`TRUE` or `FALSE`), indicating whether the filter should be applied just once. The default is `FALSE`. +- `once`: A boolean flag (`TRUE` or `FALSE`), indicating whether to apply the filter just once. The default is `FALSE`. - `queries`: An array of SELECT statements defining the specific events to filter. The SELECT syntax follows standard SQL conventions, allowing for conditions (`WHERE`), logical operators (`AND`, `OR`), and specifying particular fields or using `*` for all fields within a collection or stream. @@ -30,9 +30,10 @@ The SELECT syntax follows standard SQL conventions, allowing for conditions (`WH ## Use Cases and Examples -In practice, leveraging event delivery queries allows for highly customizable data streams, catering to a wide array of application needs. Whether you're monitoring real-time updates from a specific dataset or listening for changes that meet particular criteria, these queries empower you to streamline data reception, ensuring your application only processes the most relevant information. To demonstrate the practical application of these filters, this section explores how to subscribe to and filter events using examples that mimic real-world scenarios. +In practice, leveraging event delivery queries allows for customizing data streams, catering to a wide array of application needs. Whether you're monitoring real-time updates from a specific dataset or listening for changes that meet particular criteria, these queries empower you to streamline data reception, ensuring your application only processes the most relevant information. +To demonstrate the practical application of these filters, this section explores how to subscribe to and filter events using examples that mimic real-world scenarios. -To interact with the PhotonIQ Event Delivery Service, you must use a tool that supports WebSocket connections, as traditional HTTP clients like `curl` do not accommodate the WebSocket protocol. These examples use `wscat`, a command-line tool for connecting to WebSocket servers. +To interact with the PhotonIQ Event Delivery Service, use a tool that supports WebSocket connections, as traditional HTTP clients like `curl` do not accommodate the WebSocket protocol. These examples use `wscat`, a command-line tool for connecting to WebSocket servers. These examples illustrate the versatility of event delivery queries in EDS, enabling precise control over the data stream to suit diverse application needs. Through the use of SQL-like syntax and dynamic filter management, you can efficiently tailor the event delivery to your specific requirements. @@ -62,7 +63,7 @@ This command subscribes to all changes within `CollectionName`. This is particul wscat -c 'wss://your-eds-domain/api/es/v1/subscribe?type=collection&filters={"action": "add", "once": "FALSE", "queries": ["select specificField from CollectionName where condition"]}' ``` -Subscribes to changes in `specificField` when `condition` is met. This method is ideal for situations where events are only relevant under certain conditions, reducing noise and focusing on significant data changes. For example, in a logistics application, this could be used to alert users only when shipments are delayed by more than a day or when inventory levels fall below a critical threshold, enabling timely decision-making and action. +Subscribes to changes in `specificField` that meets a `condition`. This method is ideal for situations where events are only relevant under certain conditions, reducing noise and focusing on significant data changes. For example, in a logistics application, this could be used to alert users only when shipments are delayed by more than a day or when inventory levels fall below a critical threshold, enabling timely decision-making and action. ### Dynamic Filter Management diff --git a/docs/photoniq/event-delivery/get-started-event-delivery.md b/docs/photoniq/event-delivery/get-started-event-delivery.md deleted file mode 100644 index f2c810e29a..0000000000 --- a/docs/photoniq/event-delivery/get-started-event-delivery.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -sidebar_position: 10 -title: Get Started with Event Delivery ---- - -PhotonIQ Event Delivery is a completely managed, white-glove service. Macrometa engineers will implement it for you, making sure the service is optimized and working correctly according. - -However, some people like to be more hands-on with their management. This page provides information to help you take a more active role in managing Event Delivery. - -## Prerequisites - -- To work with Macrometa streams, then you must have a [Macrometa account](https://auth-play.macrometa.io/) with sufficient permissions to create collections. Your Macrometa partners can help you get set up, or you can sign up on your own. -- Decide what kind of [collection](../../collections/) to send streaming data to. Consult with your Macrometa partners to decide what is the best option for your use case. - - [Document Collection](../../collections/documents/) - Accepts any document type. - - [Key-Value Collection](../../collections/keyvalue/) - Accepts key-value pairs, can be set up to include blobs. - -- An application to receive Event Delivery streams. -- Plan your filters, which are set by adding queries to event subscriptions. For more information, refer to [Event Delivery Queries](event-delivery-queries.md). - -## Set Up Your Stream in the GDN - -Event Delivery lets you filter events from Macrometa streams and publish events to streams, so the first step is to get your data into a collection stream in the Macrometa Global Data Network (GDN). - -A stream is a named channel for sending messages. Each stream is backed by a distributed append-only log and can be local (at one edge location only) or global (across all edge locations in the [fabric](../../geofabrics/)). - -1. (Optional) [Create a fabric](../../geofabrics/create-geofabric.md) for your collection. This allows you to decide exactly where your data lives. If you skip this step, then the collection will be in the system fabric. -2. Create a collection that you will send streaming data to. Make sure you enable streams when you create it. Instructions for each are below: - - [Create a Document Collection](../../collections/documents/create-document-store.md) - - [Create a Key-Value Collection](../../collections/keyvalue/create-key-value-store.md) - - ![New Collection Stream](/img/photoniq/event-delivery/new-collection-stream.png) - -3. [View collection settings](../../collections/view-collection-settings.md) to access the following information: - - **Resource URL** - The endpoint to send data to your collection. All messages sent here are both stored and transmitted to the stream. - - **Stream Name** - Parameter for Event Delivery endpoints. - - **Fabric Name** - Parameter for Event Delivery endpoints. In the screenshot below, the fabric name is **_system**. - - ![View Collection Settings](/img/photoniq/event-delivery/view-collection-settings.png) - -## Set Up Event Delivery - -Once your stream is set up in the GDN, you can subscribe to it with Event Delivery and manage it using the [Event Delivery API](https://www.macrometa.com/docs/apiEds#/). - -1. [Subscribe to the stream](https://www.macrometa.com/docs/apiEds#/paths/ws:-api-es-v1-subscribe/get). This includes adding any [Event Delivery queries](event-delivery-queries.md) to filter events. -2. [Publish events](https://www.macrometa.com/docs/apiEds#/paths/api-es-v1-fabric-fabricName--stream--streamName--publish/post). You can use this API endpoint or use one of the options for publishing events to the GDN stream. Events published in this matter are not stored in the collection. -3. Monitor the service using the following endpoints: - - [Retrieve metrics](https://www.macrometa.com/docs/apiEds#/paths/api-es-v1-metrics/get) - - [Health check](https://www.macrometa.com/docs/apiEds#/paths/api-es-v1-health/get) diff --git a/docs/photoniq/event-delivery/index.md b/docs/photoniq/event-delivery/index.md index d93c7d543c..305f9d61ba 100644 --- a/docs/photoniq/event-delivery/index.md +++ b/docs/photoniq/event-delivery/index.md @@ -3,44 +3,49 @@ sidebar_position: 1 title: Event Delivery --- -PhotonIQ Event Delivery delivers real-time event data to applications using WebSockets and Server-Sent Events (SSE). It allows developers to integrate event-driven functionality into applications, ensuring they receive timely updates. +PhotonIQ Event Delivery ensures the timely delivery of real-time event data to your applications, allowing developers to integrate event-driven functionality into applications, thus guaranteeing the delivery of real-time updates for making better data-driven. It does this using two methods: + +- **Websockets**: WebSockets addresses the limited unidirectional HTTP communication protocol by establishing a persistent, bi-directional communication between clients and servers, making them an ideal choice for building efficient, low-latent, real-time applications. +- **Server-Sent Events (SSE)**: An alternative to Websockets, SSE is a lightweight, unidirectional HTTP protocol for building communication channels. However, unlike the HTTP protocol, which closes a connection after receiving a response, the SSE keeps this connection open to receiving streaming updates as long as the client, thus enabling it to send real-time updates to clients. ## Benefits of Event Delivery Event Delivery offers several key advantages that enhance the functionality and responsiveness of applications: -- **Immediate Data Updates:** Event Delivery provides real-time notifications, keeping applications up-to-date with the latest events. -- **Data Stream Customization:** With SQL-like filters, users can specify which events they receive, reducing unnecessary data. -- **Quick Decision Making:** Access to real-time data helps users respond faster to changes, improving operational efficiency. +- **Operational Efficiency**: For traffic monitoring, health, delivery, and ride-hailing and communication services, real-time event delivery helps coordinate and organize work efforts, thus improving operational efficiency and productivity. +- **Improved Customer Experiences**: Real-time applications like gaming and chat messaging offer an interactive and engaging experience for users, improving individual experiences. +- **Risk Management**: Finance, health, and military organizations rely on immediate data updates to assess risks and make informed decisions. For these industries, data is time-sensitive with a short window frame for action and becomes non-relevant or less relevant after time elapses. +- **Reduces Irrelevant Data**: Event delivery offers SQL-like filters, which help users filter subscribed events, thus reducing the occurrence of irrelevant data for processing and analytics. +- **Better Decision-making**: Access to real-time, relevant data helps teams respond faster and with better-informed solutions to changes. ## Challenges Addressed by Event Delivery -Event Delivery is designed to solve specific problems related to data management and delivery in modern applications: +Event Delivery aims to solve specific problems related to data management and delivery in modern applications: - **Information Overload:** Event Delivery filters out irrelevant data, delivering only the information users need. -- **Data Reception Latency:** Real-time event delivery minimizes delays, ensuring decisions are made using the most current information. +- **Data Reception Latency:** Real-time event delivery minimizes delays, ensuring decision-making using the most current information. - **Integration Complexity:** Event Delivery uses standard SQL-like querying for easy integration with existing systems. -## Features +## Features of EDS -Event Delivery is built with a comprehensive set of features to support real-time data delivery and customization. +The PhotonIQ Event Delivery Service has comprehensive features to support real-time data delivery and customization to fit different organizational use cases. ### Real-Time Event Delivery -This feature allows for the delivery of events as they happen, utilizing WebSockets and including event de-duplication to streamline data flow. +EDS offers two methods for enabling real-time delivery of events as they occur, utilizing Websockets and including event de-duplication to reduce the occurrence of noise and irrelevant data in your data stream. ### Event Subscription and Publishing -Users have the ability to subscribe to specific events that matter to them and can publish data to the event stream, facilitating a dynamic data exchange. +Users can subscribe to specific events that matter to them and can publish data to the event stream, facilitating a dynamic data exchange. ### Advanced Filtering -Event Delivery offers SQL-like filtering capabilities, enabling precise control over the events to which users subscribe, ensuring relevance and reducing noise. +Event Delivery offers SQL-like filtering capabilities, enabling precise control over users' subscriptions to events, ensuring relevance, and reducing noise. ### Scalability and Security -Designed to accommodate large user bases, Event Delivery provides robust security measures including data encryption and user authentication, ensuring safe and scalable operations. +Designed to accommodate large user bases, Event Delivery provides robust security measures, including data encryption and user authentication, ensuring safe and scalable operations. ### Metrics and Analytics -Providing detailed insights into data usage and event trends, this feature helps users optimize their applications and make informed decisions based on analytics. +EDS provides detailed insights into the health, performance, and event trends, helping users optimize their applications and make informed decisions based on analytics. diff --git a/docs/photoniq/event-delivery/clients/connection.md b/docs/photoniq/event-delivery/managing-event-delivery-instances/connection.md similarity index 100% rename from docs/photoniq/event-delivery/clients/connection.md rename to docs/photoniq/event-delivery/managing-event-delivery-instances/connection.md diff --git a/docs/photoniq/event-delivery/managing-event-delivery-instances/index.md b/docs/photoniq/event-delivery/managing-event-delivery-instances/index.md new file mode 100644 index 0000000000..2594806df8 --- /dev/null +++ b/docs/photoniq/event-delivery/managing-event-delivery-instances/index.md @@ -0,0 +1,9 @@ +--- +title: Managing Event Delivery Instances +--- + +To optimize the performance of your event delivery service, PhotonIQ offers different ways to manage the behaviour of your EDS instances. These methods include: + +- **Query, Set and Batch**: A layer that helps you batch and run a group of queries together, instead of running each individually, thus improving efficiency. +- **Connection**: An instance with numerous methods that helps you connect, retrieve and configure connection details, and disconnect your WebSocket/SSE connection. +- **Listeners and Error Handling**: These are grouped into global, query, result, and error listeners and helps handles events. \ No newline at end of file diff --git a/docs/photoniq/event-delivery/clients/listeners-and-errors.md b/docs/photoniq/event-delivery/managing-event-delivery-instances/listeners-and-errors.md similarity index 100% rename from docs/photoniq/event-delivery/clients/listeners-and-errors.md rename to docs/photoniq/event-delivery/managing-event-delivery-instances/listeners-and-errors.md diff --git a/docs/photoniq/event-delivery/clients/query-set-and-batch.md b/docs/photoniq/event-delivery/managing-event-delivery-instances/query-set-and-batch.md similarity index 100% rename from docs/photoniq/event-delivery/clients/query-set-and-batch.md rename to docs/photoniq/event-delivery/managing-event-delivery-instances/query-set-and-batch.md diff --git a/docs/photoniq/event-delivery/quickstart-event-delivery/01-setup-event-delivery-stream.md b/docs/photoniq/event-delivery/quickstart-event-delivery/01-setup-event-delivery-stream.md new file mode 100644 index 0000000000..e23974fe88 --- /dev/null +++ b/docs/photoniq/event-delivery/quickstart-event-delivery/01-setup-event-delivery-stream.md @@ -0,0 +1,50 @@ +--- +title: Setting Up Event Stream in GDN +--- + +The Event Delivery service allows you to stream and filter events from Macrometa streams and also publish events to these streams. +Some important concepts to know: +- **Publisher**: An application or service that continuously generates data for consumption by a subscriber. Collections in the Macrometa GDN act as publishers in the Event Delivery Service (EDS) +- **Subscriber**: Subscribes to events from the publisher. Subscribers can use SQL-queries to subscribe to specific events, thus reducing noise and focusing on the necessary data. +- **Stream**: A named channel for sending messages. The GDN backs every stream in the GDN with a distributed append-only log and can be local (at one edge location only) or global (across all edge locations in the [fabric](../../../geofabrics/)). +- **Event**: Every new data point/message generated by the publisher. + +Let's set up our first stream in a GDN. + +## Prerequisites +- A [Macrometa account](https://auth-play.macrometa.io/) with sufficient permissions to create connections. Contact a Macrometa partner to sign up or [sign up](https://www.macrometa.com/sign-up) on your own. With a Macrometa account set up, you can decide what kind of collection to stream your data into. +The PhotonIQ GDN allows you to create: + - [Document Collection](../../collections/documents/) - Accepts any document type. + - [Key-Value Collection](../../collections/keyvalue/) - Accepts key-value pairs, can be set up to include blobs. + +:::tip + +Consult with Macrometa Partners to help decide the best type for your business use case. + +::: +- An application to receive event delivery streams. +- Plan your filters. Filters are set up by adding queries to event subscriptions. + + +## Set Up Your Stream in the GDN +1. (Optional) [Create a fabric](../../../geofabrics/create-geofabric.md) for your collection. A fabric allows you to decide exactly where your data lives. Skipping this step means the collection will reside in the system fabric. +1. Create a collection to receive streaming data. + +![New Collection Stream](/img/photoniq/event-delivery/new-collection-stream.png) + +:::important + +Make sure to enable streams when you [create a collection](https://www.macrometa.com/docs/collections/). + +::: + +3. Navigate to [collection settings](https://www.macrometa.com/docs/collections/view-collection-settings) to view and access information about your collection. + +![View Collection Settings](/img/photoniq/event-delivery/view-collection-settings.png) + +Your collection settings provides useful information like: +- **Resource URL** - The endpoint sending data to your collection. All messages sent here are both stored and transmitted to the stream. +- **Stream Name** - Name of our data stream. +- **Fabric Name** - Name of our fabric. +In the screenshot above, the fabric name is **_system**. + diff --git a/docs/photoniq/event-delivery/quickstart-event-delivery/02-subscribe-to-events.md b/docs/photoniq/event-delivery/quickstart-event-delivery/02-subscribe-to-events.md new file mode 100644 index 0000000000..df22893070 --- /dev/null +++ b/docs/photoniq/event-delivery/quickstart-event-delivery/02-subscribe-to-events.md @@ -0,0 +1,63 @@ +--- +sidebar_position: 2 +title: Subscribe to the Event Delivery Service (EDS) +--- + +The last guide walked us through [setting up a collection for streaming events in the CDN](01-setup-event-delivery-stream.md). Now we have set up a collection for receiving streams, let's demonstrate how to subscribe to the EDS to receive live updates using the [Event Delivery API](https://www.macrometa.com/docs/apiEds#/). + +## Subscribe to EDS + +To subscribe to events using the [Event Delivery API](https://www.macrometa.com/docs/apiEds#/): +1. [Subscribe to the stream](https://www.macrometa.com/docs/apiEds#/paths/ws:-api-es-v1-subscribe/get) by sending an API request. + +:::important + +Curl currently has no support for WebSockets, so we'll make this request using [wscat](https://github.com/WebSockets/wscat), a command line tool for establishing a connection and exchanging information with WebSockets. + +::: + +A sample subscribe API request with wscat looks like this: + +```shell +wscat -c 'wss://x/api/es/v1/subscribe?type=collection&x-customer-id=cust-edsgdn&filters={"action": "add", "once": "FALSE", "initialData":"TRUE", "queries": ["select * from sample_employees where _key=\"-K7loZ_ZzH2iEdzwYfjZ3Ok\""]}' | sed -r "s/\x1B\[([0-9]{1,2}(;[0-9]{1,2})?)?[mGK]//g" +``` + +**WHERE**: + +- `x` : Base URL + +- `wss://x/api/es/v1/subscribe?type=collection`: Endpoint for connecting and subscribing to a collection. + +- `type`: Refers to collection type + +- `filters`: To control the behaviour of your events. For example setting `initialDATA` to `TRUE` returns the original data after subscribing to a stream while a `FALSE` value only subscribes without returning the original data. Learn more about [filters and their fundamental structure](../event-delivery-queries.md). + +- `queries`: SQL statements to query and get a specific subset of data from your collection. In this sample, we're selecting all data with a `key` value of `-K7loZ_ZzH2iEdzwYfjZ3Ok`. + +:::note + +The sed regex filter at the end removes any terminal color codes and control characters and the command works without it. + +::: + + +2. Sending the following request returns the requested data with a `key` value of `-K7loZ_ZzH2iEdzwYfjZ3Ok` from the subscribed collection. + +## Receive Live Updates from Subscribed Streams + +Let's see what happens when our subscribed collection gets updated with new data. + +Change the `first_name` from 'Janenna' to 'Jenny'. + +The terminal immediately returns fresh data with the updated value of Jenny as `first_name`. + + +## Publish Events to Data Stream +Unlike subscribing that occurs through a Websocket connection, publishing an event through the EDS occurs via https so we'll make the call using a `curl` command. + +A sample publish event API call looks like this: + +```shell +curl -X POST 'x/api/es/v1/fabric//stream//publish?type=collection' -d '{"foo": "bar"}' -H x-customer-id=cust-edsgdn +``` + diff --git a/docs/photoniq/event-delivery/quickstart-event-delivery/03-monitor-events.md b/docs/photoniq/event-delivery/quickstart-event-delivery/03-monitor-events.md new file mode 100644 index 0000000000..b420ad27ff --- /dev/null +++ b/docs/photoniq/event-delivery/quickstart-event-delivery/03-monitor-events.md @@ -0,0 +1,23 @@ +--- +title: Monitor Event Delivery Metrics +--- + +EDS offers numerous metrics for monitoring and evaluating the health status of your event service. Some of these [metrics](../event-delivery-metrics.md) include: +- `es_cpu_usage_second` +- `es_errors_per_second` +- `es_memory_usage_second` + + +## Get Health Status of EDS +Performing a health status check on your EDS requires making an API call to the EDS API with a `curl` command. A sample health check API request looks like this: + +```curl -X GET 'url/api/es/v1/health'``` + +Replace url with your gdn URL. For example, the following request: + +```curl -X GET 'https://url/api/es/v1/health'``` + +**returns**: +```json +{"status":"up"} +``` diff --git a/docs/photoniq/event-delivery/quickstart-event-delivery/index.md b/docs/photoniq/event-delivery/quickstart-event-delivery/index.md new file mode 100644 index 0000000000..dbf72fcf1c --- /dev/null +++ b/docs/photoniq/event-delivery/quickstart-event-delivery/index.md @@ -0,0 +1,20 @@ +--- +sidebar_position: 2 +title: Get Started with Event Delivery +--- + +PhotonIQ event delivery offers a fully managed, comprehensive, end-to-end solution for managing and optimizing real-time data updates for organizations handling time-sensitive data. + +However, for organizations looking to be more involved with managing their event delivery service, this section acts as a guide to get started. + +## Objectives +This section will help you achieve the following tasks: +- [Setting up your first event stream in the PhotonIQ GDN](01-setup-event-delivery-stream.md) +- [Setting up event delivery and subscribing to events](02-subscribe-to-events.md) +- [Publishing these events and monitoring the service](03-monitor-events.md) + +:::note + +Read how event streams are changing how businesses make decisions. + +::: \ No newline at end of file diff --git a/docs/photoniq/faas/01-release-notes.md b/docs/photoniq/faas/01-release-notes.md index 16745aac2b..2f623fb4d3 100644 --- a/docs/photoniq/faas/01-release-notes.md +++ b/docs/photoniq/faas/01-release-notes.md @@ -3,5 +3,14 @@ sidebar_position: 2 title: Release Notes --- -## FaaS v1.001 -This represents the very first version of the PhotonIQ Function as a Service(FaaS) \ No newline at end of file +## May 2024 Release +### v1.0.0 +This represents the very first version of the PhotonIQ Function as a Service(FaaS), a solution by PhotonIQ that delivers functions as events to a global CDN. + +### Features +- **Multiple Language Support**: Compatible with Rust and Javascript. +- **Geo-replication**: Automatic distribution of function instances to all regions in your data fabric, ensuring availability and reliability. +-**Integrated Development**: Offers tools like the FaaS CLI for creating and managing functions, and dashboard for function monitoring and logging. +- **Comprehensive Logging and Monitoring**: Captures and tracks function performance metrics to diagnose issues and optimize function performance. +- **Secure Execution**: Employs robust security controls to ensure secure communications during function execution. +- **Advanced Function Capabilities**: Supports HTTP requests, interactions with various Macrometa GDN stores, environment variables, and more. \ No newline at end of file diff --git a/docs/photoniq/faas/02-quickstart/index.md b/docs/photoniq/faas/02-quickstart/index.md index ac5eaeef90..af6c845eb1 100644 --- a/docs/photoniq/faas/02-quickstart/index.md +++ b/docs/photoniq/faas/02-quickstart/index.md @@ -1,3 +1,11 @@ --- title: Quickstart ---- \ No newline at end of file +--- + + +Welcome to FaaS! This section provides you with the basics needed to start using the service. +This section will walk you through: +- [Installing the FaaS CLI](01-faas-cli-install.md) +- [Creating, testing, and building your first function](02-create-function.md) +- [Deploying your first function](03-deploy-function-to-remote.md) + diff --git a/docs/photoniq/faas/index.md b/docs/photoniq/faas/index.md index fef3d17209..4dc0a6acba 100644 --- a/docs/photoniq/faas/index.md +++ b/docs/photoniq/faas/index.md @@ -23,13 +23,3 @@ This event-driven model helps with effective resource consumption as FaaS only u - **Cost Efficiency**: Only charges for the actual compute time and resources used, which optimizes spending and reduces waste. - **Simplified Management**: Automates many operational tasks such as scaling, deployments, and maintenance, freeing up your time and resources. - **Enhanced Security**: Executes functions in a sandboxed environment, ensuring isolation and protecting against unauthorized access and attacks. - -## Features of PhotonIQ FaaS - -- **Multiple Language Support**: Offers compatibility with Rust and JavaScript. -- **Automatic Scaling**: Dynamically adjusts the number of function instances based on request volume to handle any load efficiently. -- **Geo-Replication**: Automatically distributes function instances across global locations to minimize response times and maximize availability. -- **Integrated Developer Tools**: Provides tools such as a CLI for deployment and management, and a dashboard for monitoring function metrics and logs. -- **Comprehensive Logging and Metrics**: Captures detailed logs and performance metrics to help diagnose issues and optimize function behavior. -- **Advanced Function Capabilities**: Supports HTTP requests, interactions with various Macrometa GDN stores, environment variables, and more. -- **Secure Execution**: Ensures secure communications and robust security controls for function execution and data handling. diff --git a/docs/photoniq/prerendering/01-how-prerender-works.md b/docs/photoniq/prerendering/01-how-prerender-works.md new file mode 100644 index 0000000000..56aa529914 --- /dev/null +++ b/docs/photoniq/prerendering/01-how-prerender-works.md @@ -0,0 +1,28 @@ +--- +title: How Prerendering Works +--- + +PhotonIQ Prerendering runs the full version of a web browser in a server environment and loads an entire web application like a regular browser, including Javascript execution to generate a static HTML page. Prerender takes a snapshot of this resulting HTML code and serves to clients, enhancing the search engine optimization (SEO) of websites. + +## Effects of Prerendering + +Let's explore how Prerendering affects these two classes of web visitors: + +- Human visitors +- Bots + +### Prerendering Pages for Human Visitors + +Businesses investing a considerable resources and techniques like Javascript lazy loading, image compression, caching, and other strategies to improve web page speed, performance and experience for human users need not worry about the effects of Prerendering on their human visitors as the service does not disrupt their user experience. + +![Human Visits Site](/img/photoniq/prerendering/human-visits-site.png) + +### Prerendering Pages for Bots + +Prerendering integrates with the content delivery network (CDN) situated in front of your servers to identify bots and serve them the appropriate prerendered version of your page, either for mobile or desktop devices. + +Since bots are unable to interpret JavaScript or view content hidden by lazy loading and similar web optimization techniques, a failure to present this content reduces the amount of content indexed by these web bots, negatively impacting your search engine rankings. + +Prerendering addresses this issue by converting the content on your page into a static format that bots can easily understand and crawl. +When a bot visits your site, Prerendering determines whether it is requesting the mobile or desktop version and serves the corresponding prerendered page. + diff --git a/docs/photoniq/prerendering/02-get-started/explore.md b/docs/photoniq/prerendering/02-get-started/explore.md new file mode 100644 index 0000000000..ebb9f9932a --- /dev/null +++ b/docs/photoniq/prerendering/02-get-started/explore.md @@ -0,0 +1,3 @@ +--- +title: Get Started with Prerendering +--- \ No newline at end of file diff --git a/docs/photoniq/prerendering/02-get-started/index.md b/docs/photoniq/prerendering/02-get-started/index.md new file mode 100644 index 0000000000..c361fb1e81 --- /dev/null +++ b/docs/photoniq/prerendering/02-get-started/index.md @@ -0,0 +1,90 @@ +--- +title: Get Started with Prerendering +--- + +Although PhotonIQ offers Prerendering as a completely managed, white-glove service, this guide provides a practical approach to setting up and using the service for self-starters. + +## Objectives + +This guide will help you: + +- [Set up your origin](../07-prerendering-management/manage-origins/manage-origins.md) +- [Validate and monitor Prerendering](../06-monitor-prerendering/validate-prerendering.md) +- Purge the Cache +- [Customize rendering behavior with Prerendering headers](../03-features/02-prerendering-headers/index.md) + +## Prerequisites + +- A Prerendering instance. This Instance gives you access to the service and other tools needed to use it. Contact Macrometa engineers to help set up your Prerendering Instance. +- Target domain + + +### Set Up Origin + +Before leveraging the different capabilities of Prerendering, you need to define your origin, which is the target site for Prerendering. This step is crucial as it helps the system to understand the source of the pages and determine the caching strategy for ensuring optimal performance. For example, a regularly-updated products page may require shorter periods between subsequent caches than a contact page. + +To set up your origin: + +1. Navigate to **Origin Settings** on your [Prerendering dashboard](../07-prerendering-management/index.md) +1. Click **Add Origin URL** +1. Configure your origin by filling the values for the following fields. + - **Subdomain** - (Optional) Enter the target subdomain of the domain for Prerendering + - **Domain** - Select the target domain for prerender. + - **Sitemap Paths** - (Optional) Click **Add Sitemap Path** and add the path to the sitemap. + + :::important + + Adding a sitemap is needed if you intend to use a prefetching strategy, i.e, using Prerender to prefetch the URLs in your site. + + ::: + - **Enable Caching** - Click to turn on caching, and select the cache expiration time (also called time to live (ttl)) in days. + +![setup origin](/img/photoniq/prerendering/set-up-origin.png) + +You can further increase the capabilities of Prerendering by configuring the following settings: + +1. (Optional) If using the web console, you can [add a 404 identifier](../07-prerendering-management/manage-404-identifiers.md) by adding an identifier string. A 404 identifier helps Prerendering accurately report 404s. +1. (Optional) [Review and update Prerendering settings](../07-prerendering-management/prerendering-settings.md) for your origin. This configuration updates may include customizing the URL block list and adding various types of headers. +1. (Optional) If you are using a prefetching strategy, then [configure prefetching](../04-prerendering-strategies/01-prefetching/configure-prefetching.md). +1. (Optional) Set up [synthetic interactions](../03-features/01-synthetic-interactions/01-implementing-interaction/index.md). + 1. [Find the HTML selector](../03-features/01-synthetic-interactions/01-implementing-interaction/index.md) that you want to act on. + 2. Create a synthetic interaction policy: + - [Add a scroll interaction policy](../03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-scroll-interactions.md). + - [Add a click interaction policy](../03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-click-interactions.md). + - [Add a hover interaction policy](../03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-hover-interactions.md). + +### Validate and Monitor Prerendering + +After setting up your origin for Prerendering, you can validate its operations and performance by observing monitoring metrics. + +Navigate to **Activity** on your Prerendering dashboard to view metrics like: + +- Renders +- Request per second +- Usage highlights which provides information on other metrics like cache hits and misses, requests, prefetches, and failed requests. + +![Usage highlights](/img/photoniq/prerendering/prerendering-metrics.png) + +### Purge the Cache as Needed + +Prerendering has a [cache manager](../07-prerendering-management/manage-cache/manage-cache.md), which allows you to view information about the existing caches. + +To manage your cache, navigate to the **Cache Manager**. If you need to refresh your cached content, then you can [clear the cache](../07-prerendering-management/manage-cache/). + +This allows for targeted cache removal, specifying only the URLs you wish to clear. When accessing a URL with a cleared cache using the render endpoint, prerender automatically renders the page and caches it to ensure optimal delivery. + +![cache manager](/img/photoniq/prerendering/cache-manager.png) + +### Customize with Prerendering Headers + +[Prerendering headers](../03-features/02-prerendering-headers/index.md) help guide how Prerender renders your pages to bots. For example, you can configure Prerender to render a page in a specified language using the pass-through header. + +To customize with a pass-through header: +1. Navigate to **Advanced Settings** on your Prerendering Instance. +1. Scroll to **Pass-through Headers** and click **Add Pass-through Headers** +1. Enter the `Accept-language` header and click **Save**. + +![pass-through header](/img/photoniq/prerendering/accept-language.png) + +This header transmits any language preferences for bots to Prerendering. For example, if the bots request contains preference for english, it passes this preference into the header, so Prerendering renders the web content in English. + diff --git a/docs/photoniq/prerendering/03-features/01-synthetic-interactions/01-implementing-interaction/index.md b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/01-implementing-interaction/index.md new file mode 100644 index 0000000000..108392969e --- /dev/null +++ b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/01-implementing-interaction/index.md @@ -0,0 +1,65 @@ +--- +title: Implement a Hover Synthetic Interaction +--- + +Hover synthetic interactions reveals additional links or content, enhancing content visibility for indexing by bots. Let's go through the process of implementing a hover policy for your page. + +## Objective + +This guide will walk you through the steps of creating and implementing your first hover synthetic interaction with the following steps: + +1. Finding the `htmlSelector` +1. Testing the `htmlSelector` +1. Creating a hover policy + +## Prerequisites + +- A Prerendering Instance +- URL Paths + +### Step 1: Finding the `htmlSelector` + +The `htmlSelector` is a unique string for identifying elements on a webpage based on their HTML structure. It is critical for performing synthetic interactions effectively and accurately, ensuring the correct targeting of elements during the automation of interactions in configuring prerendering behavior. The `htmlSelector` is contained within the DOM or the shadow DOM of the web page. + +To find the `htmlSelector`: +1. Open Developer tools on your web browser + +- For **Chrome, Edge, and Firefox**: Press `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (Mac). +- For **Safari**: Enable Developer menu from the `Advanced` tab from Safari's Preferences and press `Cmd+Option+I`. +2. Use the `Elements` tab (named `Inspector` in Firefox) to view the HTML structure of the page. You can hover over different parts of the HTML code, and the corresponding parts of the web page will be highlighted. +3. Identify and copy the selector. Refer to these [recommendations when choosing a selector](../02-managing-interactions/index.md) + +### Step 2: Testing the `htmlSelector` + +After identifying a potential `htmlSelector`, it's important to test its functionality to observe its behavior in prerendering scenarios. To test the selector: + +1. Find and click on the `Console` tab from the Developer Tools. The console helps run Javascript code directly against the current viewing page. +2. Use the `document.querySelector()` method to test your selector. This method returns the first element within the document that matches the specified selector, or `null` if there are no matches. For example: +- Type `document.querySelector("yourSelector")` into the console, replacing `"yourSelector"` with the CSS selector you want to test and Press `Enter` to run the command. For instance, If you want to test a selector for an element with the ID `login-button`, you would type: + +```javascript +document.querySelector("#login-button") +``` +If the selector is correct and the element exists, the console will display the HTML of that element. If the selector is incorrect or no element matches, it will return `null`. + +3. Inspect the output to ensure it returns the intended element. Double-check your selectors for typos, incorrect classes, or IDs if testing the selector returns a `null` value. +4. Modify and test your selector incase of any errors. This iterative process ensures the accuracy and efficiency of your selectors. + +### Step 3: Create a Hover Policy + +Now we have a selector, we can go ahead to create a hover policy: +1. Navigate to **Synthetic Interactions** on your instance. +1. Click **Add Policy** and configure the following details: +- Select **Hover** as the **Interaction Type** +- Select **Specific** as the **Interaction Scope**. This setting means our interaction will apply to a specific page. +- Choose a **Device Type**, and enter a **Waiting Time After Interaction Execution** in ms. +- Enter the chosen and tested `htmlSelector` from previous steps. +- (Specific policies only) In **URL Paths**, enter one or more URL paths to which the policy will either apply or be excluded from, depending on which operator you select. +- (Specific policies only) In the **Operator** field, select on of the following: + - **Equal** - Applies the policy to all specified URL paths. + - **Not equal** - Applies the policy to all origin URLs except the specified URL paths. +- Select the **Operator** applied on the URL paths + +![create hover policy](/img/photoniq/prerendering/hover-policy.png) + +3. Click **Add Policy** diff --git a/docs/photoniq/prerendering/03-features/01-synthetic-interactions/02-managing-interactions/best-practices-using-selectors.md b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/02-managing-interactions/best-practices-using-selectors.md new file mode 100644 index 0000000000..9676880316 --- /dev/null +++ b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/02-managing-interactions/best-practices-using-selectors.md @@ -0,0 +1,45 @@ +--- +title: Best Practices for using HTML Selecctors +--- + +HTML selectors play an essential role in configuring prerendering behavior like setting up synthetic interactions to improve content rendering when serving up pages to bots. These best practices ensure your selectors are reliable, maintainable, and effective in driving the intended synthetic interactions: + +## Prioritize Stability in Selectors + +Choose selectors that are less likely to change. Avoid using dynamically generated classes or IDs that might vary between sessions or deployments. Opt for selectors based on stable structural elements or attributes that are consistent across different states of the application. + +### Use Data Attributes + +Consider using custom data attributes (for example, `data-test-id="submit-button"`) for critical elements that are interacted with during synthetic interactions. This approach isolates the selector from style and structural changes, making your tests more resilient to changes in the design. + +### Minimize Dependency on DOM Structure + +Avoid selectors that are overly dependent on the DOM hierarchy, such as descendant selectors that traverse multiple layers (such as `div > ul > li > a`). These can break if there are changes in the structure of the DOM. Instead, use direct child selectors (such as `div > a`) or even better, selectors that target elements directly. + +### Incorporate Robustness to Dynamic Content + +For elements that might appear as part of dynamic content loading, ensure your selectors are robust. This might involve waiting for elements to become visible or checking for the presence of an element before interacting with it in your scripts. + +### Explicit State Selectors + +For interactions like hover or focus, explicitly define selectors that mimic these states. For example, using `:hover` or `:focus` within your CSS or when scripting interactions to ensure that the state is considered during the prerendering process. + +### Testing and Validation + +Regularly test your selectors as part of your prerendering process. Ensure they not only find the elements but also trigger the intended interactions correctly across all scenarios and edge cases. + +### Document Selector Intent + +Clearly document the target for each selector and why, especially for those involved in synthetic interactions. This documentation is invaluable for maintenance and when the need for modifications arises as the application evolves. + +### Cross-Browser Compatibility + +Verify that your selectors and their synthetic interactions work consistently across all targeted browsers. This ensures that the prerendered content behaves as expected, regardless of the user's browser. + +### Feedback Loops + +Implement mechanisms to capture and review the success rate of interactions triggered by your selectors. Use this feedback to refine and improve the selector strategy continuously. + +### Accessibility Considerations + +Ensure that the elements targeted for synthetic interactions are also accessible. This not only improves the quality of your prerendered pages but also ensures compliance with web accessibility standards. diff --git a/docs/photoniq/prerendering/03-features/01-synthetic-interactions/02-managing-interactions/index.md b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/02-managing-interactions/index.md new file mode 100644 index 0000000000..e94f6786a2 --- /dev/null +++ b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/02-managing-interactions/index.md @@ -0,0 +1,39 @@ +--- +title: Using HTML Selectors +--- + +HTML Selectors are the primary identifier used by Prerendering for implementing synthetic interactions like Hover and Click. The `htmlSelector` resides within the DOM or the shadow DOM of the web page. + +- **Document Object Model (DOM):** This is the standard model that describes the arrangement of all elements in a web page. The DOM represents the document as a tree of objects, which can be manipulated with languages like JavaScript. + +- **Shadow DOM:** This forms a part of the web standards allows developers to create their own encapsulated HTML tags, styles, and scripts, without worrying about them conflicting with other parts of the web page. It effectively shields a part of the page’s HTML from being affected by the main document's CSS and JavaScript. This is particularly useful in complex web applications and components like web components, where you want to keep the component's internal functionality separate and hidden from the rest of the application. + +For elements encapsulated within a shadow DOM, prepend the selector with `>>>` to ensure Prerendering can accurately target and interact with these elements. The `>>>` notation allows the selector to "pierce" through the shadow boundary, enabling interaction with elements that are otherwise encapsulated. + +## Recommendations for Choosing an HTML Selector + +Here are some recommendations when choosing a selector: + + +### Use the ID + +The `id` attribute serves as a unique identifier for a html element, and can serve as a straightforward selector. Example: `#login-button`. + +### Use a Complex Selector + +For elements without an `id`, or in need of a more specific path, use the right-click context menu over the highlighted HTML code in the Developer Tools and select `Copy > Copy selector`. This gives you a string that uniquely identifies the element in CSS terms. This might be a combination of element types, classes, IDs, and pseudo-classes. + +### For Shadow DOM Elements + +If the element is within a shadow DOM, use `>>>` followed by the specific selector. For example, `>>> #__next > div > header > div.chakra-container.css-1ichkct > div > div.chakra-stack.css-jojt9m > a.chakra-link.css-i0nad5`. + +- You might need to use JavaScript to access the shadowRoot of the custom element. For example: `document.querySelector('custom-element').shadowRoot.querySelector('element')`. +- Some browsers' Developer Tools allow you to inspect elements within Shadow DOM directly. Ensure to enable the option to show user agent shadow DOM from the settings of the Developer Tools. + +#### Consider Specificity and Efficiency + +The automatically generated selector might not always be the most efficient or simplest. It might be overly specific. Simplify the selector if possible, keeping only the parts that are necessary to uniquely identify the element. + +For example, if the generated selector is `html > body > div:nth-child(3) > div > p > a`, and you know the `div` element has the id `login-container`, you might simplify this to `#login-container > p > a`. + + diff --git a/docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/index.md b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/index.md new file mode 100644 index 0000000000..f8a3093f1a --- /dev/null +++ b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/index.md @@ -0,0 +1,61 @@ +--- +title: Managing Synthetic Interaction Policies +--- + +Prerendering allows you to create policies to govern the behavior of synthetic interactions. These policies give you room to customize and specify the HTML tags where these interactions should occur, providing you with control over what content is exposed to bots. Additionally, you can configure multiple interactions per page to cater to complex dynamic sites. + +You have several options for managing Prerendering synthetic interaction policies. + +- **Synthetic Interactions tab** - You can manage synthetic interaction policies for an origin on the Synthetic Interactions tab in the web console. +- **REST API** - Macrometa provides several API calls that allow you to manage synthetic interaction policies. + +## Types of Synthetic Interaction Policies + +Synthetic interaction can be _global_ or _specific_. + +- A _global_ policy applies to all sites in the origin. +- A _specific_ policy applies only to selected URL paths. + + +## Enable/Disable Policies + +Prerendering offers two methods for enabling and disabling synthetic interaction policies. + +- **Synthetic Interactions tab** - Enable or disable interaction policies for an origin on the Synthetic Interactions tab in the web console. +- **REST API** - Macrometa provides an API call that allows you to enable or disable interaction policies for an origin. + +### Enable or Disable All Policies + +Follow these instructions to enable or disable all synthetic interaction policies of a particular type in the web console. There is no API endpoint to perform this task. + +1. Log in to your Prerendering dashboard. +2. Click **Synthetic Interactions**. +3. Select an origin to enable or disable policies for. +4. Click the toggle next to the name of the type of policy to enable or disable. + +![Enable or Disable All Synthetic Interactions](/img/prerendering/enable-disable-all-synthetic-interactions.png) + +## Enable or Disable Specific Policies + + + + +Follow these instructions to enable or disable specific synthetic interaction policies in the web console. + +1. Log in to your Prerendering dashboard. +2. Click **Synthetic Interactions**. +3. Select an origin to enable or disable policies for. +4. Click to expand the type of policy that you want to enable or disable. +5. Click the pencil icon next to the policy that you want to enable or disable. +6. Click the **Active** toggle to enable or disable the interaction. +7. Click **Update**. + + The displayed status changes to reflect the new status, either **Active** or **Inactive**. + + + + +[Update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). + + + diff --git a/docs/photoniq/prerendering/synthetic-interactions/manage-click-interactions.md b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-click-interactions.md similarity index 71% rename from docs/photoniq/prerendering/synthetic-interactions/manage-click-interactions.md rename to docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-click-interactions.md index c5fe9849d4..27964d8347 100644 --- a/docs/photoniq/prerendering/synthetic-interactions/manage-click-interactions.md +++ b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-click-interactions.md @@ -5,11 +5,8 @@ title: Manage Click Interaction Policies import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -You have several options for managing Prerendering click synthetic interaction policies. +Prerendering uses policies to manage every synthetic interaction. This page will guide you through creating and managing click policies by using the web console and API Reference. -- **Synthetic Interactions tab** - You can manage synthetic click interaction policies for an origin on the Synthetic Interactions tab in the web console. - ![Prerendering Synthetic Interactions Tab - Click](/img/prerendering/synthetic-interactions-click.png) -- **REST API** - Macrometa provides several API calls that allow you to manage synthetic click interaction policies. ## View Click Policies @@ -20,36 +17,40 @@ Follow these instructions to view click policies in the web console. 1. Log in to your Prerendering dashboard. 2. Click **Synthetic Interactions**. -3. Select an origin to view scroll policies for. +3. Select an origin to view the click policies. 4. Click to expand **Click** to view existing policies. -Use our interactive API Reference with code generation in 18 programming languages to: - - [Get all synthetic interactions](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions/get) - [Get a specific synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/get) -## Click Policy Fields +## Explore the Fields in a Click Policy + +Prerendering provides the following information about click synthetic interaction policies. + +:::important + +Field names in the web console are different than those in the API responses. Refer to the [API documentation](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch) to test the endpoints. -Prerendering provides the following information about click synthetic interaction policies. Field names in the web console are different than those in the API responses. Refer to the API endpoint documentation for a full explanation of the API response. +::: -### Global +### Global Policy -Global policies are applied to all origin URLs. +Global policies are applied to all origin URLs. The following fields are found in a global policy: - **Sequence** - Policy execution order. - **Status** - Whether the policy is active or inactive. -- **HTML Selector** - HTML selector where the policy is executed. For more information about HTML selectors, refer to [Find HTML Selector](find-htmlselector.md). +- **HTML Selector** - Identifier that tells Prerendering where to apply the synthetic interaction. - **Wait After** - Waiting time (in milliseconds) after the policy is executed. - **Devices** - Icons indicating whether the policy is for desktop devices, mobile devices, or both. - **Actions** - Click an icon to edit or delete a policy. -### Specifics +### Specific Policy Specific policies are applied only to the URLs specified in the policy. If the policies conflict, then the specific policy takes precedence. @@ -57,7 +58,7 @@ Specific policies are applied only to the URLs specified in the policy. If the p - **Status** - Whether the policy is active or inactive. - **URL Paths** - Origin paths where the specific policy is evaluated to be executed. - **Operator** - **Equal** or **Not equal**. -- **HTML Selector** - HTML selector where the policy is executed. For more information about HTML selectors, refer to [Find HTML Selector](find-htmlselector.md). +- **HTML Selector** - HTML selector where the policy is executed. For more information about HTML selectors, refer to [using HTML Selectors](../02-managing-interactions/index.md). - **Wait After** - Waiting time (in milliseconds) after the policy is executed. - **Devices** - Icons indicating whether the policy is for desktop devices, mobile devices, or both. - **Actions** - Click an icon to edit or delete a policy. @@ -74,7 +75,7 @@ Follow these instructions to add a new click policy in the web console. 3. Select the origin that you want to create the new policy for. 4. Click **Add Policy**. 5. In the **Interaction Type** field, select **Click**. -6. If you want the policy to be active immediately, then leave the **Active** toggle on. If you want the policy inactive, then click to turn it off. +6. Leave the **Active** toggle on if you want to activate the policy immediately, else, click to turn it off. 7. In the **Interaction Scope** field, select one of the following: - **Global** - The policy will apply to all origin URLs. - **Specific** - (Default) The policy will apply only to specific URL paths. @@ -83,7 +84,7 @@ Follow these instructions to add a new click policy in the web console. - **Mobile** - Policy will apply only to mobile devices. - **All** - (Default) Policy will apply to both desktop and mobile devices. 9. In the **Waiting Time After Interaction Execution** field, enter the time in milliseconds that Prerendering should wait after executing the interaction before executing the next interaction. -10. In the **HTML Selector** field, enter the `htmlSelector` that you want the policy to execute upon. For more information about HTML selectors, refer to [Find HTML Selector](find-htmlselector.md). +10. In the **HTML Selector** field, enter the `htmlSelector` that you want the policy to execute upon. 11. (Specific policies only) In **URL Paths**, enter one or more URL paths to which the policy will either apply or be excluded from, depending on which operator you select. 12. (Specific policies only) In the **Operator** field, select on of the following: - **Equal** - Applies the policy to all specified URL paths. @@ -95,7 +96,7 @@ Follow these instructions to add a new click policy in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [create a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/post). +[Create a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/post). @@ -117,7 +118,7 @@ Follow these instructions to update a click interaction policy in the web consol -Use our interactive API Reference with code generation in 18 programming languages to [update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). +[Update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). @@ -153,7 +154,7 @@ Follow these instructions to delete a click interaction policy in the web consol -Use our interactive API Reference with code generation in 18 programming languages to [delete a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/delete). +[Delete a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/delete). diff --git a/docs/photoniq/prerendering/synthetic-interactions/manage-hover-interactions.md b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-hover-interactions.md similarity index 80% rename from docs/photoniq/prerendering/synthetic-interactions/manage-hover-interactions.md rename to docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-hover-interactions.md index 3c065c707b..bf795feb12 100644 --- a/docs/photoniq/prerendering/synthetic-interactions/manage-hover-interactions.md +++ b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-hover-interactions.md @@ -27,8 +27,6 @@ Follow these instructions to view hover policies in the web console. -Use our interactive API Reference with code generation in 18 programming languages to: - - [Get all synthetic interactions](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions/get) - [Get a specific synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/get) @@ -37,20 +35,20 @@ Use our interactive API Reference with code generation in 18 programming languag ## Hover Policy Fields -Prerendering provides the following information about hover synthetic interaction policies. Field names in the web console are different than those in the API responses. Refer to the API endpoint documentation for a full explanation of the API response. +Prerendering provides the following information about hover synthetic interaction policies. Field names in the web console are different than those in the API responses. Refer to the API documentation for a full explanation of the API response. -### Global +### Global Policy Global policies are applied to all origin URLs. - **Sequence** - Policy execution order. - **Status** - Whether the policy is active or inactive. -- **HTML Selector** - HTML selector where the policy is executed. For more information about HTML selectors, refer to [Find HTML Selector](find-htmlselector.md). +- **HTML Selector** - HTML selector that executes the policy. - **Wait After** - Waiting time (in milliseconds) after the policy is executed. - **Devices** - Icons indicating whether the policy is for desktop devices, mobile devices, or both. - **Actions** - Click an icon to edit or delete a policy. -### Specifics +### Specific Policy Specific policies are applied only to the URLs specified in the policy. If the policies conflict, then the specific policy takes precedence. @@ -58,7 +56,7 @@ Specific policies are applied only to the URLs specified in the policy. If the p - **Status** - Whether the policy is active or inactive. - **URL Paths** - Origin paths where the specific policy is evaluated to be executed. - **Operator** - **Equal** or **Not equal**. -- **HTML Selector** - HTML selector where the policy is executed. For more information about HTML selectors, refer to [Find HTML Selector](find-htmlselector.md). +- **HTML Selector** - HTML selector that executes the policy. Here are some [recommendations for choosing a `htmlSelector`](../02-managing-interactions/index.md) - **Wait After** - Waiting time (in milliseconds) after the policy is executed. - **Devices** - Icons indicating whether the policy is for desktop devices, mobile devices, or both. - **Actions** - Click an icon to edit or delete a policy. @@ -84,7 +82,7 @@ Follow these instructions to add a new hover policy in the web console. - **Mobile** - Policy will apply only to mobile devices. - **All** - (Default) Policy will apply to both desktop and mobile devices. 9. In the **Waiting Time After Interaction Execution** field, enter the time in milliseconds that Prerendering should wait after executing the interaction before executing the next interaction. -10. In the **HTML Selector** field, enter the `htmlSelector` that you want the policy to execute upon. For more information about HTML selectors, refer to [Find HTML Selector](find-htmlselector.md). +10. In the **HTML Selector** field, enter the `htmlSelector` that you want the policy to act on. 11. (Specific policies only) In **URL Paths**, enter one or more URL paths to which the policy will either apply or be excluded from, depending on which operator you select. 12. (Specific policies only) In the **Operator** field, select on of the following: - **Equal** - Applies the policy to all specified URL paths. @@ -96,7 +94,7 @@ Follow these instructions to add a new hover policy in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [create a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/post). +[Create a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/post). @@ -118,7 +116,7 @@ Follow these instructions to update a hover interaction policy in the web consol -Use our interactive API Reference with code generation in 18 programming languages to [update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). +[Update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). @@ -148,13 +146,13 @@ Follow these instructions to delete a hover interaction policy in the web consol 2. Click **Synthetic Interactions**. 3. Select the origin for which you want to delete a policy. 4. Click to expand **Hover**. -5. In the **Actions** field, click the red X icon next to the policy that you want to delete. +5. In the **Actions** field, click the red X icon next to the policy you intend to delete. 6. Click **Confirm**. -Use our interactive API Reference with code generation in 18 programming languages to [delete a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/delete). +[Delete a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/delete). diff --git a/docs/photoniq/prerendering/synthetic-interactions/manage-scroll-interactions.md b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-scroll-interactions.md similarity index 84% rename from docs/photoniq/prerendering/synthetic-interactions/manage-scroll-interactions.md rename to docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-scroll-interactions.md index e87d0fbb35..b5613520a1 100644 --- a/docs/photoniq/prerendering/synthetic-interactions/manage-scroll-interactions.md +++ b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-scroll-interactions.md @@ -26,8 +26,6 @@ Follow these instructions to view scroll policies in the web console. -Use our interactive API Reference with code generation in 18 programming languages to: - - [Get all synthetic interactions](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions/get) - [Get a specific synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/get) @@ -82,7 +80,7 @@ Follow these instructions to add a new scroll policy in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [create a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/post). +[Create a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/post). @@ -106,7 +104,7 @@ Follow these instructions to update a scroll global configuration in the web con -Use our interactive API Reference with code generation in 18 programming languages to [update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). +[Update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). @@ -128,7 +126,7 @@ Follow these instructions to update a scroll interaction policy in the web conso -Use our interactive API Reference with code generation in 18 programming languages to [update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). +[Update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). @@ -150,7 +148,7 @@ Follow these instructions to delete a specific scroll interaction policy in the -Use our interactive API Reference with code generation in 18 programming languages to [delete a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/delete). +[Delete a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/delete). diff --git a/docs/photoniq/prerendering/03-features/01-synthetic-interactions/index.md b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/index.md new file mode 100644 index 0000000000..9745642f3b --- /dev/null +++ b/docs/photoniq/prerendering/03-features/01-synthetic-interactions/index.md @@ -0,0 +1,28 @@ +--- +title: Synthetic Interactions +--- + +Synthetic interactions are automated actions that Prerendering performs on your web page to simulate real user behavior. These actions include scrolling, hovering over elements, and clicking buttons or tabs. Synthetic interactions fully renders dynamic content on the page for easier and faster accessibility by search engine bots or other web crawlers. + +With synthetic interactions, Prerendering enables you to maximize the visibility of your dynamically generated content, ensuring a more effective indexing by web crawlers. + +## Supported Interactions + +Prerendering supports a variety of synthetic interactions. You can create as many policies for each type of interaction as you need. + +### Scroll + +Loading a webpage leaves some parts of it, like the footer unloaded, until a user scrolls to it. With a [scroll synthetic interaction](../01-synthetic-interactions/03-managing-synthetic-interaction-policies/manage-scroll-interactions.md), Prerendering automatically scrolls to ensure the rendering of such content. This automatic scrolling loads and captures more content, enhancing the completeness of the prerendered page for scanning by bots and web crawlers. + +### Click + +Click events, such as tab switching, can be defined by the user to reveal additional links or content to bots. For example, clicking to switch tabs or expand sections. Simulating these clicks during prerendering ensures content visibility during indexing by bots. + +### Hover + +Hovering is especially useful for menu bars as it reveals additional links or content for bots to find and index. By simulating these hover actions during prerendering, these hidden content becomes findable and accessible for indexing by search engines. + + +## Importance of Synthetic Interactions + +Web crawlers like search engine bots only see content rendered on a page. Without synthetic interactions, any dynamically loaded information remains hidden from these bots. Implementing synthetic interactions ensures that all your page's content gets crawled, making it more visible and accessible on search engines, and thus improving SEO performance. diff --git a/docs/photoniq/prerendering/prerendering-headers/_category_.json b/docs/photoniq/prerendering/03-features/02-prerendering-headers/_category_.json similarity index 100% rename from docs/photoniq/prerendering/prerendering-headers/_category_.json rename to docs/photoniq/prerendering/03-features/02-prerendering-headers/_category_.json diff --git a/docs/photoniq/prerendering/prerendering-headers/allowlist-value-headers.md b/docs/photoniq/prerendering/03-features/02-prerendering-headers/allowlist-value-headers.md similarity index 67% rename from docs/photoniq/prerendering/prerendering-headers/allowlist-value-headers.md rename to docs/photoniq/prerendering/03-features/02-prerendering-headers/allowlist-value-headers.md index 916b7e5ce7..bcd5ddb5f0 100644 --- a/docs/photoniq/prerendering/prerendering-headers/allowlist-value-headers.md +++ b/docs/photoniq/prerendering/03-features/02-prerendering-headers/allowlist-value-headers.md @@ -3,7 +3,7 @@ sidebar_position: 30 title: Allowlist-Based Header Values --- -Allowlist-based header values help confirm the legitimacy of requests coming from the Prerendering service to your origin server, ensuring both security and integrity. +Allowlist-based header values confirms the legitimacy of requests coming from the Prerendering service to your origin server, ensuring both security and integrity. ### What Are Allowlist-Based Header Values? @@ -17,4 +17,5 @@ Allowlist-based header values are custom headers that act as a security mechanis ### How Do Allowlist-Based Header Values Work? -When a page is being prerendered—either on-demand or during prefetching—the Prerendering service attaches an allowlist-based header value to the request sent to your origin server. Your server, configured to recognize this header, validates the request before proceeding with the rendering process. +When prerendering a page—either on-demand or during prefetching, the Prerendering service attaches an allowlist-based header value to the request sent to your origin server. Your server, configured to recognize this header, validates the request before proceeding with the rendering process. + diff --git a/docs/photoniq/prerendering/prerendering-headers/caching-control-headers.md b/docs/photoniq/prerendering/03-features/02-prerendering-headers/caching-control-headers.md similarity index 100% rename from docs/photoniq/prerendering/prerendering-headers/caching-control-headers.md rename to docs/photoniq/prerendering/03-features/02-prerendering-headers/caching-control-headers.md diff --git a/docs/photoniq/prerendering/prerendering-headers/index.md b/docs/photoniq/prerendering/03-features/02-prerendering-headers/index.md similarity index 94% rename from docs/photoniq/prerendering/prerendering-headers/index.md rename to docs/photoniq/prerendering/03-features/02-prerendering-headers/index.md index 12b5961d36..9c92770980 100644 --- a/docs/photoniq/prerendering/prerendering-headers/index.md +++ b/docs/photoniq/prerendering/03-features/02-prerendering-headers/index.md @@ -3,8 +3,6 @@ sidebar_position: 20 title: Prerendering Headers --- -# Headers in Prerendering - Headers in Prerendering allow you to tailor the prerendering process to your specific requirements. You can exercise control over prerendering behavior with customizable passthrough, allowlist, and caching control headers. You can specify which pages should be prerendered based on unique attributes, allowing you to focus on a specific user base. diff --git a/docs/photoniq/prerendering/prerendering-headers/passthrough-headers.md b/docs/photoniq/prerendering/03-features/02-prerendering-headers/passthrough-headers.md similarity index 100% rename from docs/photoniq/prerendering/prerendering-headers/passthrough-headers.md rename to docs/photoniq/prerendering/03-features/02-prerendering-headers/passthrough-headers.md diff --git a/docs/photoniq/prerendering/03-features/index.md b/docs/photoniq/prerendering/03-features/index.md new file mode 100644 index 0000000000..b1bc6e5eb2 --- /dev/null +++ b/docs/photoniq/prerendering/03-features/index.md @@ -0,0 +1,9 @@ +--- +title: Explore Prerendering Features +--- + +Prerendering offers numerous features that improve availability, reliability and accessibility of website content to web crawlers. Some of these features include: + +- Synthetic interactions +- Prerendering headers +- Performance optimization with advanced user settings. diff --git a/docs/photoniq/prerendering/manage-prefetching/configure-prefetching.md b/docs/photoniq/prerendering/04-prerendering-strategies/01-prefetching/configure-prefetching.md similarity index 75% rename from docs/photoniq/prerendering/manage-prefetching/configure-prefetching.md rename to docs/photoniq/prerendering/04-prerendering-strategies/01-prefetching/configure-prefetching.md index d43c01e85c..fe3b5986d5 100644 --- a/docs/photoniq/prerendering/manage-prefetching/configure-prefetching.md +++ b/docs/photoniq/prerendering/04-prerendering-strategies/01-prefetching/configure-prefetching.md @@ -1,5 +1,4 @@ --- -sidebar_position: 30 title: Configure Prefetching --- import Tabs from '@theme/Tabs'; @@ -26,7 +25,7 @@ Follow these instructions to view prefetching jobs in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [get prefetching configuration](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-configs/get). +[Get prefetching configuration](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-configs/get). @@ -47,7 +46,7 @@ Prerendering provides the following prefetching configuration fields. Field name -A new prefetch configuration appears in the web console when you add a new origin in the Origin Settings tab. For more information about viewing and adding origins, refer to [Manage Origins](../manage-origins/). +A new prefetch configuration appears in the web console when you add a new origin in the Origin Settings tab. For more information about viewing and adding origins, refer to [Manage Origins](../../../07-prerendering-management/manage-origins/). The new configuration is inactive and unscheduled. Follow these instructions in order to activate it: @@ -64,12 +63,12 @@ The new configuration is inactive and unscheduled. Follow these instructions in -Use our interactive API Reference with code generation in 18 programming languages to [create a prefetching configuration](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-configs/post). +[Create a prefetching configuration](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-configs/post). -## Edit Prefetching Configurations +## Edit Prefetching Configuration @@ -89,11 +88,11 @@ Follow these instructions to edit a prefetching in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [get prefetching configuration](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-configs/get). +[Get prefetching configuration](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-configs/get). -## Delete Prefetching Configurations +## Delete Prefetching Configuration -Use our interactive API Reference with code generation in 18 programming languages to [delete a prefetching configuration](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-configs/delete). +[Delete a prefetching configuration](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-configs/delete). diff --git a/docs/photoniq/prerendering/manage-prefetching/index.md b/docs/photoniq/prerendering/04-prerendering-strategies/01-prefetching/index.md similarity index 89% rename from docs/photoniq/prerendering/manage-prefetching/index.md rename to docs/photoniq/prerendering/04-prerendering-strategies/01-prefetching/index.md index ac3ddc4cd6..7e249d8003 100644 --- a/docs/photoniq/prerendering/manage-prefetching/index.md +++ b/docs/photoniq/prerendering/04-prerendering-strategies/01-prefetching/index.md @@ -1,6 +1,5 @@ --- -sidebar_position: 1 -title: Manage Prefetching +title: Prefetching --- Macrometa provides options so that you can monitor the status and activity of prefetching either in the web console or using API endpoints, and you can configure prefetching jobs. diff --git a/docs/photoniq/prerendering/manage-prefetching/view-prefetching.md b/docs/photoniq/prerendering/04-prerendering-strategies/01-prefetching/view-prefetching.md similarity index 76% rename from docs/photoniq/prerendering/manage-prefetching/view-prefetching.md rename to docs/photoniq/prerendering/04-prerendering-strategies/01-prefetching/view-prefetching.md index dd637f25b7..20ffa62fef 100644 --- a/docs/photoniq/prerendering/manage-prefetching/view-prefetching.md +++ b/docs/photoniq/prerendering/04-prerendering-strategies/01-prefetching/view-prefetching.md @@ -1,11 +1,10 @@ --- -sidebar_position: 20 title: View Prefetching --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -You have several options for viewing Prerendering prefetching that is in progress or already completed. +You have several options for viewing Prerendering prefetching in progress or already completed. - **Prefetching tab** - In the Prefetching tab in the web console, you can view in-progress prefetching and prefetch history for an origin. - **REST API** - Macrometa provides a API calls that allow you to view prefetch information. @@ -27,7 +26,7 @@ Follow these instructions to view current prefetching in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [get prefetch URLs](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-urls/get). +[Get prefetch URLs](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--prefetch-urls/get). @@ -68,14 +67,14 @@ Follow these instructions to view prefetch history in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [get prefetch statistics](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-metrics-stats-prefetch-origin/get). +[Get prefetch statistics](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-metrics-stats-prefetch-origin/get). ## Prefetching History Fields -Prerendering provides the following prefetching history fields. Field names in the web console are different than those in the API responses. Refer to the API endpoint documentation for a full explanation of the API response. +Prerendering provides the following prefetching history fields. - **Type** - Whether prefetching was scheduled or done manually. - **Total** - Total number of URLs to be prefetched. diff --git a/docs/photoniq/prerendering/04-prerendering-strategies/index.md b/docs/photoniq/prerendering/04-prerendering-strategies/index.md new file mode 100644 index 0000000000..fda15c6576 --- /dev/null +++ b/docs/photoniq/prerendering/04-prerendering-strategies/index.md @@ -0,0 +1,25 @@ +--- +title: Prerendering Strategies +--- + +Prerendering offers two strategies for rendering web pages to bots and web crawlers: prefetching and on-demand prerendering. + +### Prefetching + +With a prefetching strategy, Prerendering uses your sitemap to crawl and prerender all pages on your origin site. These prerendered pages are ready for bot access, whether they end up being visited or not. + +This Prerendering strategy allows you to schedule content at intervals for prefetching. These intervals range from daily to weekly and is useful for irregularly updated content that require thorough crawling by bots. + +![Bot Visits Prefetched Site](/img/photoniq/prerendering/bot-visits-site.png) + +### On-demand Prerendering + +Unlike prefetching, on-demand prerendering only renders a page after a bot requests for it. For uncached pages, Prerendering fetches and renders the page before serving to the bot, and then caches the page for a specific period. + +Prerendering allows you to define the caching periods when [configuring your origin](../07-prerendering-management/manage-origins/). + +![Bot Visits On-Demand Prerendered Site](/img/photoniq/prerendering/on-demand-prerender.png) + +Prerendering offers numerous flexible options when setting caching parameters, including cache duration or to manually clear the cache if needed. Clearing the cache works for frequently changing content or for very hands-on Prerendering users. + +![Cache Refresh](/img/photoniq/prerendering/refresh-cache.png) diff --git a/docs/photoniq/prerendering/monitor-prerendering/_category_.json b/docs/photoniq/prerendering/06-monitor-prerendering/_category_.json similarity index 100% rename from docs/photoniq/prerendering/monitor-prerendering/_category_.json rename to docs/photoniq/prerendering/06-monitor-prerendering/_category_.json diff --git a/docs/photoniq/prerendering/06-monitor-prerendering/index.md b/docs/photoniq/prerendering/06-monitor-prerendering/index.md new file mode 100644 index 0000000000..6fd9cb7e66 --- /dev/null +++ b/docs/photoniq/prerendering/06-monitor-prerendering/index.md @@ -0,0 +1,8 @@ +--- +sidebar_position: 1 +title: Monitor Prerendering +--- + +Macrometa provides options for monitoring the status and activity of Prerendering either in the web console or using API endpoints. + + diff --git a/docs/photoniq/prerendering/monitor-prerendering/validate-prerendering.md b/docs/photoniq/prerendering/06-monitor-prerendering/validate-prerendering.md similarity index 69% rename from docs/photoniq/prerendering/monitor-prerendering/validate-prerendering.md rename to docs/photoniq/prerendering/06-monitor-prerendering/validate-prerendering.md index 97096c3670..ff3893aa5e 100644 --- a/docs/photoniq/prerendering/monitor-prerendering/validate-prerendering.md +++ b/docs/photoniq/prerendering/06-monitor-prerendering/validate-prerendering.md @@ -1,9 +1,11 @@ --- sidebar_position: 80 -title: Validate Prerendering +title: Monitor and Validate Prerendering --- -In order to confirm Prerendering is running, you can check the the health endpoint or view a prerendered page as if you were a bot and see what the bot sees. Understanding what a web crawler sees when it visits your site can help you fine-tune your prerendering settings. +In order to confirm Prerendering is running, Prerendering allows you to view a rendered page from a bot standpoint to understand what a web crawler sees when it visits your site, thus allowing you to optimize rendering behavior. + +Furthermore, you can check the health status of your Prerendering service by using the health endpoint. ## Check Prerendering Health @@ -15,5 +17,5 @@ Here are ways to view the prerendered pages: 1. **Use Developer Tools**: Many modern browsers have developer tools that allow you to emulate different user agents, including web crawlers. Switch to a crawler user agent and reload the page to see the prerendered version. 2. **API Endpoints**: Use the [Get prerendered page](/docs/apiPrerendering#/paths/api-prerender-v1-render-mobile---url/get) endpoint to view the prerendered page. -3. **View Cached Pages**: In the Cache Manager tab, you can [view cached pages](../manage-cache/manage-cache.md). +3. **View Cached Pages**: In the Cache Manager tab, you can [view cached pages](../07-prerendering-management/manage-cache/). 4. **Third-Party Tools**: There are online services that allow you to view your site from the perspective of a search engine bot. These tools fetch the prerendered page and display it, giving you a clear idea of what is being served to the crawlers. diff --git a/docs/photoniq/prerendering/monitor-prerendering/view-prerendering-activity.md b/docs/photoniq/prerendering/06-monitor-prerendering/view-prerendering-activity.md similarity index 96% rename from docs/photoniq/prerendering/monitor-prerendering/view-prerendering-activity.md rename to docs/photoniq/prerendering/06-monitor-prerendering/view-prerendering-activity.md index 093e038876..5fd3e3d51c 100644 --- a/docs/photoniq/prerendering/monitor-prerendering/view-prerendering-activity.md +++ b/docs/photoniq/prerendering/06-monitor-prerendering/view-prerendering-activity.md @@ -26,8 +26,6 @@ Follow these instructions to view prerendering activity in the web console. -Use our interactive API Reference with code generation in 18 programming languages to: - - [Get render-stats metrics](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-metrics-stats-render/get) - [Get render-stats metrics by origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-metrics-stats-render-origin/get) - [Get usage metrics](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-usage-aggregationType/get) diff --git a/docs/photoniq/prerendering/monitor-prerendering/view-render-history.md b/docs/photoniq/prerendering/06-monitor-prerendering/view-render-history.md similarity index 100% rename from docs/photoniq/prerendering/monitor-prerendering/view-render-history.md rename to docs/photoniq/prerendering/06-monitor-prerendering/view-render-history.md diff --git a/docs/photoniq/prerendering/07-prerendering-management/index.md b/docs/photoniq/prerendering/07-prerendering-management/index.md new file mode 100644 index 0000000000..7d49ff13db --- /dev/null +++ b/docs/photoniq/prerendering/07-prerendering-management/index.md @@ -0,0 +1,19 @@ +--- +title: Explore the Prerendering Dashboard +--- + +Prerendering offers its interactive dashboard, which allows you to view and manage your rendered pages. + +![Prerendering dashboard](/img/prerendering/prerendering-dashboard.png) + +This dashboard lets you perform the following tasks: + +- [View and manage Prerendering activity with the Activity Tab](../06-monitor-prerendering/view-prerendering-activity.md) +- [Manage your origin(s) with Origin Settings](./manage-origins/) +- [Manage the Cache with the Cache Manager](./manage-cache/manage-cache.md) +- [Configure and manage Prefetching](../04-prerendering-strategies/01-prefetching/configure-prefetching.md) +- [Monitor your Render History](../06-monitor-prerendering/view-render-history.md) +- [View and manage Synthetic Interactions](../03-features/01-synthetic-interactions/01-implementing-interaction/index.md) +- [Enable better 404 reporting with the 404 Identifier](manage-404-identifiers.md) +- [Optimize Prerendering with the Advanced Settings](prerendering-settings.md) + diff --git a/docs/photoniq/prerendering/manage-404-identifiers.md b/docs/photoniq/prerendering/07-prerendering-management/manage-404-identifiers.md similarity index 82% rename from docs/photoniq/prerendering/manage-404-identifiers.md rename to docs/photoniq/prerendering/07-prerendering-management/manage-404-identifiers.md index de2ea1094a..77f566f132 100644 --- a/docs/photoniq/prerendering/manage-404-identifiers.md +++ b/docs/photoniq/prerendering/07-prerendering-management/manage-404-identifiers.md @@ -18,7 +18,7 @@ Prerendering provides the following fields in the 404 Identifier tab. Field name - **Origin URL** - URL of the origin. - **Identifier String** - Text that signals the prerendering bot to set the response code to 404. - **Date Added** - Date the origin was added. -- **Actions** - Click the pencil to add or edit text. +- **Actions** - Allows you to add or edit text. ## View 404 Identifiers @@ -33,7 +33,7 @@ Follow these instructions to view 404 identifiers in the web console. -In the API, 404 identifier information is included in the origin settings API. Use our interactive API Reference with code generation in 18 programming languages to: +The origin settings API reference contains 404 identifier information: - [Get origins](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins/get) - [Get an origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin/get) @@ -58,7 +58,7 @@ Follow these instructions to add or update 404 identifiers in the web console. -In the API, 404 identifier information is included in the origin settings API. Use our interactive API Reference with code generation in 18 programming languages to [update the origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins/patch). +Update the 404 identifier with the [update the origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins/patch) API endpoint. diff --git a/docs/photoniq/prerendering/manage-cache/_category_.json b/docs/photoniq/prerendering/07-prerendering-management/manage-cache/_category_.json similarity index 100% rename from docs/photoniq/prerendering/manage-cache/_category_.json rename to docs/photoniq/prerendering/07-prerendering-management/manage-cache/_category_.json diff --git a/docs/photoniq/prerendering/manage-cache/manage-cache.md b/docs/photoniq/prerendering/07-prerendering-management/manage-cache/manage-cache.md similarity index 79% rename from docs/photoniq/prerendering/manage-cache/manage-cache.md rename to docs/photoniq/prerendering/07-prerendering-management/manage-cache/manage-cache.md index aa3ddf5bf8..7a5c1a63d8 100644 --- a/docs/photoniq/prerendering/manage-cache/manage-cache.md +++ b/docs/photoniq/prerendering/07-prerendering-management/manage-cache/manage-cache.md @@ -36,7 +36,7 @@ Follow these instructions to view cached documents in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [Get all cached documents](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--cache/get). +[Get all cached documents](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--cache/get). @@ -57,7 +57,7 @@ Follow these instructions to clear cached documents in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [Purge the cache](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--cache-purge/post). +[Purge the cache](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--cache-purge/post). @@ -78,7 +78,7 @@ Follow these instructions to view cached documents in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [Preview a cached document](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--cache--cacheKey--preview/get). +[Preview a cached document](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--cache--cacheKey--preview/get). diff --git a/docs/photoniq/prerendering/manage-origins/_category_.json b/docs/photoniq/prerendering/07-prerendering-management/manage-origins/_category_.json similarity index 100% rename from docs/photoniq/prerendering/manage-origins/_category_.json rename to docs/photoniq/prerendering/07-prerendering-management/manage-origins/_category_.json diff --git a/docs/photoniq/prerendering/manage-origins/manage-origins.md b/docs/photoniq/prerendering/07-prerendering-management/manage-origins/manage-origins.md similarity index 82% rename from docs/photoniq/prerendering/manage-origins/manage-origins.md rename to docs/photoniq/prerendering/07-prerendering-management/manage-origins/manage-origins.md index 71e59d7cc4..f23994bed6 100644 --- a/docs/photoniq/prerendering/manage-origins/manage-origins.md +++ b/docs/photoniq/prerendering/07-prerendering-management/manage-origins/manage-origins.md @@ -5,7 +5,7 @@ title: Manage Origin Settings import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -You have several options for viewing Prerendering origin settings. +Prerendering offers different options for viewing and managing your origin settings. - **Origin Settings tab** - In the Origin Settings tab in the web console, you can view and update information about each origin. To add a new origin domain, contact Macrometa Support. ![Prerendering Origin Settings Tab](/img/prerendering/origin-settings.png) @@ -24,8 +24,6 @@ Follow these instructions to view origin settings in the web console. -Use our interactive API Reference with code generation in 18 programming languages to: - - [Get origins](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins/get) - [Get an origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin/get) @@ -65,7 +63,7 @@ Follow these instructions to add new origin settings in the web console. To add -Use our interactive API Reference with code generation in 18 programming languages to [create an origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins/post). +[Create an origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins/post). @@ -85,7 +83,7 @@ Follow these instructions to update origin settings in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [update an origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin/patch). +[Update an origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin/patch). @@ -105,7 +103,7 @@ Follow these instructions to delete origin settings in the web console. -Use our interactive API Reference with code generation in 18 programming languages to [delete an origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin/delete). +[Delete an origin](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin/delete). diff --git a/docs/photoniq/prerendering/prerendering-settings.md b/docs/photoniq/prerendering/07-prerendering-management/prerendering-settings.md similarity index 83% rename from docs/photoniq/prerendering/prerendering-settings.md rename to docs/photoniq/prerendering/07-prerendering-management/prerendering-settings.md index 0025fc4bb0..69cd4f6ec0 100644 --- a/docs/photoniq/prerendering/prerendering-settings.md +++ b/docs/photoniq/prerendering/07-prerendering-management/prerendering-settings.md @@ -31,7 +31,7 @@ Follow these instructions to view prerendering activity in the web console. -Use our interactive API Reference with code generation in 18 programming languages to: +Use our interactive API Reference to: - [Get Prerender settings](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--settings/get). - [Update Prerender settings](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--settings/patch) @@ -42,16 +42,9 @@ Use our interactive API Reference with code generation in 18 programming languag -## Update Settings +## Optimizing with Advanced Settings -Use our interactive API Reference with code generation in 18 programming languages to: - -- [Update prerender settings](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--settings/patch). -- [Update origin settings](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin/patch) - -## Prerendering Settings - -Prerendering provides the following settings. Field names in the web console are different than those in the API responses. Refer to the API endpoint documentation for a full explanation. +Configuring settings available in the Advanced settings tab allows you to optimize how Prerendering renders your pages. ### Optimized Rendering for Different Crawling Bots @@ -95,7 +88,7 @@ You can block specific external URLs during rendering. Click **Edit** to update ### Allow Origin Header Value -In the web console, this displays the origin allowlist value if one is set. For more information about allowlist headers, refer to [Allowlist-Based Header Values](prerendering-headers/allowlist-value-headers.md). +In the web console, this displays the origin allowlist value if one is set. For more information about allowlist headers, refer to [Allowlist-Based Header Values](../03-features/02-prerendering-headers/allowlist-value-headers.md). ![Allow Origin Header Value](/img/prerendering/allow-origin-header-value.png) diff --git a/docs/photoniq/prerendering/08-Tutorials/choose-caching-strategy.md b/docs/photoniq/prerendering/08-Tutorials/choose-caching-strategy.md new file mode 100644 index 0000000000..0bd62b4d46 --- /dev/null +++ b/docs/photoniq/prerendering/08-Tutorials/choose-caching-strategy.md @@ -0,0 +1,3 @@ +--- +title: How to choose the best caching strategy for your business +--- \ No newline at end of file diff --git a/docs/photoniq/prerendering/08-Tutorials/improve-rendering-behavior.md b/docs/photoniq/prerendering/08-Tutorials/improve-rendering-behavior.md new file mode 100644 index 0000000000..85e4cf8a01 --- /dev/null +++ b/docs/photoniq/prerendering/08-Tutorials/improve-rendering-behavior.md @@ -0,0 +1,3 @@ +--- +title: How to improve the quality of your rendered pages +--- \ No newline at end of file diff --git a/docs/photoniq/prerendering/best-practices-prerendering.md b/docs/photoniq/prerendering/09-best-practices-prerendering.md similarity index 89% rename from docs/photoniq/prerendering/best-practices-prerendering.md rename to docs/photoniq/prerendering/09-best-practices-prerendering.md index 84bcb98dad..5dc5560d7d 100644 --- a/docs/photoniq/prerendering/best-practices-prerendering.md +++ b/docs/photoniq/prerendering/09-best-practices-prerendering.md @@ -13,19 +13,19 @@ Be very careful when configuring your origins for prerendering. Incorrect settin Take advantage of the caching feature to serve the static version of your website's page faster. By using this feature, the pages are cached and served to the bots without the need of prerendering them again. Configure the cache expiration time according to how frequently your website is modified. -For more information about managing the Prerendering cache, refer to [Manage Cache](manage-cache). +For more information about managing the Prerendering cache, refer to [Manage Cache](./07-prerendering-management/manage-cache/manage-cache.md). ## Remove or Update Dead Links Dead links negatively affect both your SEO rankings and the cost of prerendering. Regularly scan your website for dead links and either remove them or update them to point to active pages. This improves user experience and ensures you're not incurring extra charges for prerendering pages that don't contribute to your site's value. -If you have a system that redirects users to a page that provides a 404 experience if they stumble on something that isn't covered, then you might want to add a 404 identifier to Prerendering. For more information, refer to [Manage 404 Identifiers](manage-404-identifiers). +If you have a system that redirects users to a page that provides a 404 experience if they stumble on something that isn't covered, then you might want to add a 404 identifier to Prerendering. For more information, refer to [Manage 404 Identifiers](./07-prerendering-management/manage-404-identifiers.md). ## Regularly Review Prerendering Performance Metrics Examine the performance metrics generated by the prerendering service. These metrics provide valuable insights into user experience and identify areas for further optimization. Make a habit of checking these metrics at regular intervals to stay ahead of any issues. -For more information about monitoring Prerendering metrics, refer to [Monitor Prerendering](monitor-prerendering). +For more information about monitoring Prerendering metrics, refer to [Monitor Prerendering](./06-monitor-prerendering/view-prerendering-activity.md). ## Disable Cookie Consent Banner diff --git a/docs/photoniq/prerendering/get-started-prerendering.md b/docs/photoniq/prerendering/get-started-prerendering.md deleted file mode 100644 index 99e1c5b133..0000000000 --- a/docs/photoniq/prerendering/get-started-prerendering.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_position: 10 -title: Get Started with Prerendering ---- - -PhotonIQ Prerendering is a completely managed, white-glove service. Macrometa engineers will implement for you, making sure the service is optimized and working correctly according to the prerendering strategy that you choose. - -However, some people like to be more hands-on with their management. After you work with Macrometa engineers to set up your Prerendering instance, follow these steps to get started prerendering a new origin. - -## Set Up the Origin - -Before leveraging the caching capabilities of Prerendering service, you must first define your origin, which is the site that you want it to prerender. This step is crucial as it allows the system to understand the source of the pages and how they should be cached for optimal performance. - -1. [Create an origin](manage-origins/manage-origins.md#create-an-origin). -2. (Optional) If using the web console, then you can [add a 404 identifier](manage-404-identifiers.md#add-or-update-404-identifiers) so that Prerendering can accurately report 404s. -3. (Optional) [Review and update Prerendering settings](prerendering-settings.md) for your origin. This can include customizing the URL block list and adding various types of headers. -4. (Optional) If you are using a prefetching strategy, then [configure prefetching](manage-prefetching/configure-prefetching.md). -5. (Optional) Set up [synthetic interactions](./synthetic-interactions/). - 1. [Find the HTML selector](./synthetic-interactions/find-htmlselector.md) that you want to act on. - 2. Create a synthetic interaction policy: - - [Add a scroll interaction policy](./synthetic-interactions/manage-scroll-interactions.md#add-scroll-policies). - - [Add a click interaction policy](./synthetic-interactions/manage-click-interactions.md#add-click-policies). - - [Add a hover interaction policy](./synthetic-interactions/manage-hover-interactions.md#add-hover-policies). - -## Validate and Monitor Prerendering - -Once your origin is set up, you should validate that Prerendering is working as expected and monitor performance metrics. - -1. [Validate Prerendering](monitor-prerendering/validate-prerendering.md) using one the API, web console, or other tools. -2. Monitor Prerendering: - - [View Prerendering activity](./monitor-prerendering/view-prerendering-activity.md). - - [View rendering history](./monitor-prerendering/view-render-history.md). - - [View prefetching](./manage-prefetching/view-prefetching.md) if you are using a prefetching strategy. - -## Purge the Cache as Needed - -If you need to refresh your cached content, then you can [clear the cache](./manage-cache/manage-cache.md#clear-the-cache). - -This allows for targeted cache removal, specifying only the URLs you wish to clear. If a cleared URL is later accessed using the render endpoint and caching is enabled, then the service will automatically prerender and cache the page again for optimal delivery. diff --git a/docs/photoniq/prerendering/how-prerender-works.md b/docs/photoniq/prerendering/how-prerender-works.md deleted file mode 100644 index 971fea52c5..0000000000 --- a/docs/photoniq/prerendering/how-prerender-works.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_position: 5 -title: How Prerendering Works ---- - -PhotonIQ Prerendering generates static HTML pages from dynamic websites or web applications to enhance the search engine optimization (SEO) of websites. This page provides a high-level explanation of how the service operates. - -## Human Visitors - -Companies invest considerable resources in optimizing pages for human users, focusing on both speed and design. Techniques such as JavaScript, lazy loading, and other strategies are employed to make sites quick and visually appealing. Prerendering does not disrupt this user experience. - -![Human Visits Site](/img/photoniq/prerendering/human-visits-site.png) - -## Prerendering Pages for Bots - -Prerendering integrates with the content delivery network (CDN) situated in front of your servers. The service collaborates with the CDN to identify bots and serve them the appropriate prerendered version of the page, either for mobile or desktop devices. - -Because bots cannot interpret JavaScript or view content hidden by lazy loading and similar techniques, failing to present this content can negatively impact your search engine rankings. Prerendering addresses this issue by converting the content on your page into a static format that bots can easily understand and crawl. When a bot visits your site, Prerendering determines whether it is requesting the mobile or desktop version and serves the corresponding prerendered page. - -## Prefetching vs. On-demand Prerendering - -Prerendering offers two strategies: prefetching and on-demand prerendering. - -### Prefetching - -With the prefetching strategy, Prerendering uses your sitemap to crawl and prerender all pages on your origin site. These prerendered pages are ready for bot access, whether they end up being visited or not. - -You can schedule content to be refreshed or prerendered again at intervals ranging from daily to weekly. This strategy is most useful for content that doesn't change frequently and is expected to be thoroughly crawled by bots. - -![Bot Visits Prefetched Site](/img/photoniq/prerendering/bot-visits-site.png) - -### On-demand Prerendering - -In on-demand prerendering, a page is not prerendered until a bot requests it for the first time. If a bot requests a page not already in the cache, Prerendering fetches and renders the page before serving it to the bot. The rendered page may then be cached for a specific period, to fulfill future requests before the cache expires. - -![Bot Visits On-Demand Prerendered Site](/img/photoniq/prerendering/on-demand-prerender.png) - -You have the flexibility to set caching parameters, including cache duration. Additionally, you can manually clear the cache if needed. This strategy is ideal for frequently changing content or for those who prefer more hands-on management of the prerendering process. - -![Cache Refresh](/img/photoniq/prerendering/refresh-cache.png) diff --git a/docs/photoniq/prerendering/index.md b/docs/photoniq/prerendering/index.md index 76dceeaa17..52b23eb96c 100644 --- a/docs/photoniq/prerendering/index.md +++ b/docs/photoniq/prerendering/index.md @@ -3,59 +3,53 @@ sidebar_position: 1 title: Prerendering --- -PhotonIQ Prerendering offers a robust solution for enhancing SEO and website performance for enterprise-level companies. This service generates static HTML from dynamic sites, ideal for JavaScript-heavy websites. It ensures complete rendering of web elements like tabs and scrolls, improving search engine visibility and indexing speed. Key features include geo-replicated caching for fast, global web page delivery with current SEO and analytics. +PhotonIQ Prerendering offers a no-code, robust solution for enhancing SEO and website performance for enterprise-level companies. This service generates static HTML from dynamic sites, ensuring the complete rendering of web elements like tabs and scrolls, improving search engine visibility and indexing speed, making it ideal for JavaScript-heavy websites. -As a no-code, scalable solution, Prerendering integrates seamlessly with existing web frameworks, catering to the needs of marketing and web teams in large enterprises. It boosts organic traffic, enhances user experience, and provides a competitive advantage by saving time and resources. Macrometa offers a fully managed service, implementing and optimizing the solution within 30 days. +As a no-code, scalable solution, Prerendering integrates seamlessly with existing Javascript web frameworks, improving speed and agility during implementation. It also caters to the needs of marketing and web teams in large enterprises, boosting organic traffic, enhancing user experience, and providing a competitive advantage by saving time and resources. +Furthermore, Prerendering offers geo-replicated caching for fast, global web page delivery with current SEO and analytics. -### How It Works +Macrometa offers Prerendering as a fully managed service, implementing and optimizing the solution within 30 days. However, for a more practical introduction, you can get started with the service by [setting up your origin](./02-get-started/index.md) -Prerendering works by running a full version of a web browser, such as Chrome, in a server environment. This browser loads the entire web application, including executing all JavaScript, just like a user's browser would. Once the JavaScript has finished executing, the prerendering service takes a snapshot of the resulting HTML and serves this static version to the client. +## Key Features of Prerendering -For a more detailed explanation, refer to [How Prerendering Works](how-prerender-works.md). - -## Benefits of PhotonIQ Prerendering - -PhotonIQ Prerendering provides a comprehensive suite of features and advantages, essential for enhancing website performance and SEO for enterprise-level companies. By implementing this service, businesses can experience a significant improvement in their online presence and user engagement. Here are the key benefits: - -- **Advanced Page Rendering with Synthetic Actions:** Mimics live user interactions for a fully-rendered page, including tabs, scrolls, and content below the fold. This ensures that all aspects of a web page are visible and indexable by search engines. -- **Geo-Replicated Caching:** Once a page is rendered, it's stored and delivered globally or regionally via a CDN. This leads to faster page load times and a consistent user experience across different geographies. -- **Optimized Crawl Budget Utilization:** With a hydration time of P90 or 50 ms, PhotonIQ makes the most of your crawl budget, allowing search engines to index more pages and more relevant content. -- **Framework Agnostic, No-Code Solution:** This fully managed service easily integrates with various frameworks, requiring no code changes, making it versatile and easy to implement. -- **Increased Indexing of Pages:** Enhances your site's crawl budget, leading to more pages being indexed. This results in more relevant content being visible to search engines, closely aligning with what real users see. -- **Time Efficiency:** Improves SEO scores faster and simplifies the implementation process, saving valuable time. -- **Fast Page Indexing:** Accelerates the process of getting web pages indexed by search engines. -- **Turnkey Implementation:** Offers a straightforward and less complicated setup process, facilitating quicker adoption and integration. - -By leveraging these benefits, PhotonIQ Prerendering not only improves website visibility and performance but also streamlines the process of managing and optimizing web content for search engines and users alike. - -## Features - -Key capabilities of Prerendering include: - -### Customization and Content Delivery +### Customization and Seamless Content Delivery - **Two Prerendering Strategies**: Choose between two distinct prerendering methods to enhance SEO and performance. Opt for a fully prerendered site that's ready for search engine bots or render pages on-demand based on bot visits. Select the approach that aligns best with your performance needs and traffic patterns. - **Device Type Management**: Ensure an optimized user experience with device-specific prerendering. Prerendering delivers static mobile pages to mobile browser bots and static desktop pages to desktop browser bots. This enables a seamless experience across multiple devices. -- **Customizable Headers**: Gain control over prerendering behavior with customizable passthrough, allowlist, and cache-control headers. Specify which pages should be prerendered based on unique attributes. For example, target only English-language pages for prerendering, allowing you to focus on a specific user base. For more information, refer to [Headers in Prerendering](prerendering-headers/index.md). -- **Synthetic Interactions**: Address content visibility issues arising from user interactions like scroll, click, or hover. Synthetic interactions can trigger this hidden content, ensuring it is included in the prerendered page. This ensures that all essential content is accessible to search engine bots, even if it normally requires user interaction to appear. For more information, refer to [Synthetic Interactions in Prerendering](./synthetic-interactions/index.md). -- **Public Access Not Required**: Extend prerendering capabilities to non-publicly accessible sites. Whether you're working on a staging environment or a restricted development site, Macrometa engineers can assist in setting up prerendering without requiring public access. +- **Customizable Headers**: Gain control over prerendering behavior with [customizable headers](./03-features/02-prerendering-headers/index.md). These headers guide how prerender renders pages to bots, for example, the [pass-through header](./03-features/02-prerendering-headers/passthrough-headers.md) offers language customization via its `Accept-Language` headers, allowing you to focus on a specific user base. +- **Synthetic Interactions**: Address content visibility issues arising from user interactions like scroll, click, or hover. [Synthetic interactions](./03-features/01-synthetic-interactions/01-implementing-interaction/index.md) mimic and render hidden content from interactions like scroll and hover, ensuring their visibility in the prerendered page. This visibility ensures accessibility to essential content by search engine bots, even for those requiring user interaction. +- **Easy, safe and accessible implementation**: Extend prerendering capabilities to non-publicly accessible sites. From staging environment to a restricted development site, Macrometa engineers are available for configuring prerendering for different levels of access. - **Link Previews**: Enhance social media visibility with integrated Open Graph tags in prerendered pages. This feature ensures that link previews on social media platforms display the intended image, title, and description, optimizing engagement and click-through rates. By including relevant Open Graph tags, PhotonIQ's prerendering service makes content more shareable and visually appealing on social media, improving your brand's online presence. ### Performance -- **Caching**: Boost speed by storing results from resource-intensive operations or retaining static resources for immediate retrieval. +- **Geo-replicated Caching**: Boost speed and availability by storing results from resource-intensive operations or retaining static resources for immediate retrieval, reducing consumption of server resources. - **Load Balancing**: Evenly distribute incoming traffic across multiple servers. This balance ensures no single server gets overburdened, promoting consistent application reliability. - **Scalability**: Tailored for large-scale prerendering challenges. The service uses a distributed compute strategy, potentially running numerous instances in a given region to manage high-traffic demands. ### Reliability and Security -- **Fault Tolerance and Resiliency**: Built to address server or network disruptions. In the event of network issues, the service opts to serve older, reliable data over rejecting the request. -- **Rate Limiting**: Implement limits on client request frequency to deter misuse and ensure everyone gets a fair share of the resources. -- **Authorization**: Access and configuration of the prerendering service require proper user authorization. +- **Fault Tolerance and Resiliency**: In the event of network issues, the service serves older, reliable data over rejecting the request, ensuring continuous availability. +- **Rate Limiting**: Implement limits on client request frequency to deter misuse and ensure proper allocation of resources to various departments. +- **Authorization**: Accessing and configuring the prerendering service requires proper user authorization from Macrometa to proceed. ### Monitoring and Management -- **Fully Managed**: Prerendering is a white glove, fully-managed service. -- **Metrics and Monitoring**: Track performance indicators like request counts, cache metrics, and latency. Regularly send telemetry data and logs to monitoring platforms for proactive management. -- **Audit Events**: Maintain transparency by logging events when configurations are created, updated, or deleted. -- **Deployer and Deployment Pipelines**: Streamline the integration and delivery workflow, ensuring updates are rolled out efficiently and safely. +- **Fully Managed**: Prerendering is a white glove, fully-managed service, allowing your engineers to focus on other important engineering tasks. +- **Metrics and Monitoring**: Track and evaluate performance indicators like request counts, cache metrics, and latency. Regularly send telemetry data and logs to monitoring platforms for proactive management. +- **Audit Events**: Establish a trail of configuration events to maintain transparency for audits. +- **Deployer and Deployment Pipelines**: Streamline the integration and delivery workflow, ensuring rolling updates are efficient and safe. + + +## Benefits of PhotonIQ Prerendering + +PhotonIQ Prerendering provides a comprehensive suite of features and advantages, essential for enhancing website performance and SEO for small and large businesses. By implementing this service, businesses experience a significant improvement in their SEO performance, boosting their online presence and user engagement. Here are some other key benefits: + +- **Advanced Page Rendering:** Prerendering synthetic interactions mimics and renders live user interactions like tabs, scrolls, and hidden content for a fully-rendered page. These interactions ensure that all aspects of a web page are visible and indexable by search engines. +- **Improved Website Performance:** Prerendering stores its rendered pages in a cache and delivers it globally or regionally via a CDN, causing faster page load times and a consistent user experience across different geographical regions. +- **Optimized Crawl Budget Utilization:** With a hydration time of P90 or 50 ms, PhotonIQ makes the most of your crawl budget, allowing search engines to index more pages and more relevant content. +- **Framework Agnostic, No-Code Solution:** This fully managed service easily integrates with various frameworks, requiring no code changes, making it versatile and easy to implement. +- **Faster Page Indexing:** Accelerates the process of getting web pages indexed by search engines. +- **Turnkey Implementation:** Offers a straightforward and less complicated setup process, facilitating quicker adoption and integration. + +By leveraging these benefits, PhotonIQ Prerendering improves website visibility and performance, while also managing and optimizing web content for search engines and users alike. diff --git a/docs/photoniq/prerendering/manage-prefetching/_category_.json b/docs/photoniq/prerendering/manage-prefetching/_category_.json deleted file mode 100644 index 8a7816c7a8..0000000000 --- a/docs/photoniq/prerendering/manage-prefetching/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Manage Prefetching", - "position": 70 -} diff --git a/docs/photoniq/prerendering/monitor-prerendering/index.md b/docs/photoniq/prerendering/monitor-prerendering/index.md deleted file mode 100644 index 51601fbe2e..0000000000 --- a/docs/photoniq/prerendering/monitor-prerendering/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -sidebar_position: 1 -title: Monitor Prerendering ---- - -Macrometa provides options so that you can monitor the status and activity of Prerendering either in the web console or using API endpoints. - - diff --git a/docs/photoniq/prerendering/synthetic-interactions/_category_.json b/docs/photoniq/prerendering/synthetic-interactions/_category_.json deleted file mode 100644 index 73bc2f07e4..0000000000 --- a/docs/photoniq/prerendering/synthetic-interactions/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Synthetic Interactions", - "position": 20 -} diff --git a/docs/photoniq/prerendering/synthetic-interactions/enable-disable-policies.md b/docs/photoniq/prerendering/synthetic-interactions/enable-disable-policies.md deleted file mode 100644 index 8c8d13c88d..0000000000 --- a/docs/photoniq/prerendering/synthetic-interactions/enable-disable-policies.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 80 -title: Enable/Disable Policies ---- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -You have several options for enabling and disabling Prerendering synthetic interaction policies. - -- **Synthetic Interactions tab** - You can view enable or disable interaction policies for an origin on the Synthetic Interactions tab in the web console. -- **REST API** - Macrometa provides an API call that allows you to enable or disable interaction policies for an origin. - -## Enable or Disable All Policies - -Follow these instructions to enable or disable all synthetic interaction policies of a particular type in the web console. There is no API endpoint to perform this task. - -1. Log in to your Prerendering dashboard. -2. Click **Synthetic Interactions**. -3. Select an origin to enable or disable policies for. -4. Click the toggle next to the name of the type of policy that you want to enable or disable. - -![Enable or Disable All Synthetic Interactions](/img/prerendering/enable-disable-all-synthetic-interactions.png) - -## Enable or Disable Specific Policies - - - - -Follow these instructions to enable or disable specific synthetic interaction policies in the web console. - -1. Log in to your Prerendering dashboard. -2. Click **Synthetic Interactions**. -3. Select an origin to enable or disable policies for. -4. Click to expand the type of policy that you want to enable or disable. -5. Click the pencil icon next to the policy that you want to enable or disable. -6. Click the **Active** toggle to enable or disable the interaction. -7. Click **Update**. - - The displayed status changes to reflect the new status, either **Active** or **Inactive**. - - - - -Use our interactive API Reference with code generation in 18 programming languages to [update a synthetic interaction](https://www.macrometa.com/docs/apiPrerendering#/paths/api-prerender-v1-origins-origin--interactions--type/patch). - - - diff --git a/docs/photoniq/prerendering/synthetic-interactions/find-htmlselector.md b/docs/photoniq/prerendering/synthetic-interactions/find-htmlselector.md deleted file mode 100644 index bae51d873d..0000000000 --- a/docs/photoniq/prerendering/synthetic-interactions/find-htmlselector.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -sidebar_position: 20 -title: Find HTML Selector ---- - -# Find `htmlSelector` for Synthetic Interactions - -This document provides a comprehensive guide on how to find the `htmlSelector` necessary for configuring synthetic interactions such as clicks and hovers. The `htmlSelector` is essential for specifying which elements on a webpage should be targeted during the pre-rendering process. - -## What is `htmlSelector`? - -The `htmlSelector` is a string used to uniquely identify elements on a webpage based on their HTML structure. It is critical for performing synthetic interactions effectively and accurately, ensuring the correct elements are targeted during the automation of interactions in prerendering. - -### DOM and Shadow DOM - -The `htmlSelector` is contained within the DOM or the shadow DOM of the web page. - -- **Document Object Model (DOM):** This is the standard model that describes how all elements in a web page are arranged. The DOM represents the document as a tree of objects, which can be manipulated with languages like JavaScript. - -- **Shadow DOM:** This part of the web standards allows developers to create their own encapsulated HTML tags, styles, and scripts, without worrying about them conflicting with other parts of the web page. It effectively shields a part of the page’s HTML from being affected by the main document's CSS and JavaScript. This is particularly useful in complex web applications and components like web components, where you want to keep the component's internal functionality separate and hidden from the rest of the application. - -### Special Consideration for Shadow DOM Elements - -For elements encapsulated within a shadow DOM, prepend the selector with `>>>` to ensure Prerendering can accurately target and interact with these elements. The `>>>` notation allows the selector to "pierce" through the shadow boundary, enabling interaction with elements that are otherwise encapsulated. - -## Find the `htmlSelector` - -Finding HTML selectors effectively is a crucial skill for web developers, especially when you need to manipulate or access specific elements on a web page. Here’s a step-by-step guide to finding HTML selectors. - -### 1. Choose Your Browser and Open Developer Tools - -First, open the Developer Tools in your web browser. You can usually do this by right-clicking on an element in the page and then selecting **Inspect** or by using keyboard shortcuts: - -- For **Chrome, Edge, and Firefox**: Press `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (Mac). -- For **Safari**: First, enable the Developer menu from Safari's preferences (under the `Advanced` tab), then press `Cmd+Option+I`. - -### 2. Inspect the Element - -With the Developer Tools open, use the `Elements` tab (named `Inspector` in Firefox) to view the HTML structure of the page. You can hover over different parts of the HTML code, and the corresponding parts of the web page will be highlighted. - -### 3. Identify and Copy the Selector - -There are several considerations for choosing the selector. - -#### Use the ID - -If the element has an `id` attribute, this can serve as a straightforward selector. Example: `#login-button`. - -#### Use a Complex Selector - -For elements without an `id`, or when a more specific path is needed, use the right-click context menu over the highlighted HTML code in the Developer Tools and select `Copy > Copy selector`. This gives you a string that uniquely identifies the element in CSS terms. This might be a combination of element types, classes, IDs, and pseudo-classes. - -#### For Shadow DOM Elements - -If the element is within a shadow DOM, use `>>>` followed by the specific selector. For example, `>>> #__next > div > header > div.chakra-container.css-1ichkct > div > div.chakra-stack.css-jojt9m > a.chakra-link.css-i0nad5`. - -- You might need to use JavaScript to access the shadowRoot of the custom element. For example: `document.querySelector('custom-element').shadowRoot.querySelector('element')`. -- Some browsers' Developer Tools allow you to inspect elements within Shadow DOM directly. Ensure that the option to show user agent shadow DOM is enabled in the settings of the Developer Tools. - -#### Consider Specificity and Efficiency - -The automatically generated selector might not always be the most efficient or simplest. It might be overly specific. Simplify the selector if possible, keeping only the parts that are necessary to uniquely identify the element. - -For example, if the generated selector is `html > body > div:nth-child(3) > div > p > a`, and you know the `div` element has the id `login-container`, you might simplify this to `#login-container > p > a`. - -## Testing the `htmlSelector` - -Once you have identified a potential `htmlSelector`, it's important to test its functionality: - -### 1. Open the Console Tab in Developer Tools - -Within the Developer Tools, find and click on the `Console` tab. This is where you can run JavaScript code directly against the page you are viewing. - -### 2. Test Your Selector - -In the console, you can use the `document.querySelector()` method to test your selector. This method returns the first element within the document that matches the specified selector, or `null` if there are no matches. Here’s how to use it: - -- Type `document.querySelector("yourSelector")` into the console, replacing `"yourSelector"` with the CSS selector you want to test. -- Press `Enter` to run the command. - -**Example** - -If you want to test a selector for an element with the ID `login-button`, you would type: - -```javascript -document.querySelector("#login-button") -``` - -If the selector is correct and the element exists, the console will display the HTML of that element. If the selector is incorrect or no element matches, it will return `null`. - -### 3. Analyze the Results - -- If the element appears in the console, inspect the output to ensure it’s the correct element you intended to select. -- If `null` is returned, double-check your selector for any errors, such as typos, incorrect classes, or IDs. You may also need to ensure that the element is not dynamically loaded after some interactions, which might require waiting for certain events before the element can be targeted. - -### 4. Adjust as Necessary - -If the initial test doesn't return the correct element, then modify your selector and test again. This iterative process helps refine your selector to be both accurate and efficient. - -## Best Practices - -These best practices helps ensure that the selectors used in prerendering scenarios are reliable, maintainable, and effective in driving the intended synthetic interactions. - -### Prioritize Stability in Selectors - -Choose selectors that are less likely to change. Avoid using dynamically generated classes or IDs that might vary between sessions or deployments. Opt for selectors based on stable structural elements or attributes that are consistent across different states of the application. - -### Use Data Attributes - -Consider using custom data attributes (for example, `data-test-id="submit-button"`) for critical elements that are interacted with during synthetic interactions. This approach isolates the selector from style and structural changes, making your tests more resilient to changes in the design. - -### Minimize Dependency on DOM Structure - -Avoid selectors that are overly dependent on the DOM hierarchy, such as descendant selectors that traverse multiple layers (such as `div > ul > li > a`). These can break if there are changes in the structure of the DOM. Instead, use direct child selectors (such as `div > a`) or even better, selectors that target elements directly. - -### Incorporate Robustness to Dynamic Content - -For elements that might appear as part of dynamic content loading, ensure your selectors are robust. This might involve waiting for elements to become visible or checking for the presence of an element before interacting with it in your scripts. - -### Explicit State Selectors - -For interactions like hover or focus, explicitly define selectors that mimic these states. For example, using `:hover` or `:focus` within your CSS or when scripting interactions to ensure that the state is considered during the prerendering process. - -### Testing and Validation - -Regularly test your selectors as part of your prerendering process. Ensure they not only find the elements but also trigger the intended interactions correctly across all scenarios and edge cases. - -### Document Selector Intent - -Clearly document what each selector is targeting and why it’s chosen, especially for those involved in the synthetic interactions. This documentation is invaluable for maintenance and when modifications are needed as the application evolves. - -### Cross-Browser Compatibility - -Verify that your selectors and their synthetic interactions work consistently across all targeted browsers. This ensures that the prerendered content behaves as expected, regardless of the user's browser. - -### Feedback Loops - -Implement mechanisms to capture and review the success rate of interactions triggered by your selectors. Use this feedback to refine and improve the selector strategy continuously. - -### Accessibility Considerations - -Ensure that the elements targeted for synthetic interactions are also accessible. This not only improves the quality of your prerendered pages but also ensures compliance with web accessibility standards. diff --git a/docs/photoniq/prerendering/synthetic-interactions/index.md b/docs/photoniq/prerendering/synthetic-interactions/index.md deleted file mode 100644 index d01ba63b3d..0000000000 --- a/docs/photoniq/prerendering/synthetic-interactions/index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -sidebar_position: 20 -title: Synthetic Interactions ---- - -# Synthetic Interactions in Prerendering - -Synthetic interactions are automated actions that Prerendering performs on your web page to simulate real user behavior. These actions can include scrolling, hovering over elements, and clicking buttons or tabs. The purpose of synthetic interactions is to fully render dynamic content on the page so that it's accessible to search engine bots or other web crawlers. - -With synthetic interactions, Prerendering enables you to maximize the visibility of your dynamically generated content, ensuring a more effective indexing by web crawlers. - -A set of rules that govern a synthetic interaction is called a _policy_. The policy governs which pages the interaction is executed on, the HTML selector acted upon, and so on. - -:::note -Although synthetic interactions might make your UI appear odd during the rendering process, it doesn't impact how bots interpret the page. -::: - -## Why Synthetic Interactions Are Important - -Web crawlers, such as search engine bots, only see the content that is rendered on a page. Without synthetic interactions, any dynamically loaded information remains hidden from these bots. Implementing synthetic interactions ensures that all your page's content gets crawled, making it more visible and accessible on search engines. - -## Supported Interactions - -Prerendering supports a variety of synthetic interactions. You can create as many policies for each type of interaction as you need. - -### Scroll - -Some web content, particularly footers, might not load until the user scrolls down to it. Prerendering automatically scrolls to ensure all such content is rendered. Many web pages load content dynamically based on what's visible in the viewport. By automatically scrolling during prerendering, more content is loaded and captured, enhancing the completeness of the prerendered page. - -### Click - -Click events, such as tab switching, can be defined by the user to reveal additional links or content to bots. For example, clicking to switch tabs or expand sections. By simulating these clicks during prerendering, we can ensure that all necessary content is visible and indexed by bots. - -### Hover - -Especially useful for menu bars, hovering can reveal additional links or content that the bot should find and index. Hovering over elements such as menus often reveals additional content. By simulating these hover actions during prerendering, hidden content is exposed and accessible for indexing by search engines. - -## Global and Specific Policies - -Synthetic interactions can be _global_ or _specific_. - -- A _global_ policy applies to all sites in the origin. -- A _specific_ policy applies only to selected URL paths. - -## Customization - -You can specify the HTML tags where these interactions should occur, providing you with control over what content is exposed to bots. Additionally, you can configure multiple interactions per page to cater to complex dynamic sites. - -## HTML Selector - -To set up a synthetic interaction, you must enter the correct `htmlSelector` string so that Prerender knows which page element to interact with. For information about how to find this string, refer to [Find HTML Selector](find-htmlselector.md). diff --git a/docs/photoniq/vwrs/01-how-vwrs-works.md b/docs/photoniq/vwrs/01-how-vwrs-works.md new file mode 100644 index 0000000000..2e15ef41ca --- /dev/null +++ b/docs/photoniq/vwrs/01-how-vwrs-works.md @@ -0,0 +1,43 @@ +--- +title: How VWRs Works +--- + +Macrometa PhotonIQ Virtual Waiting Rooms (VWRs) are an advanced prioritization service that manages the flow of visitors entering a site, especially during periods of high demand. It serves as a protective layer for your origin server, effectively managing high traffic volumes to prevent server overload. + +## Solution Overview + +![VWR Solution Architecture](../../../static/img/photoniq/vwr/vwr-solution-architecture.png) + +The waiting room solution includes these essential aspects: + +- **Origin Service**: The website for which you want to set up a virtual waiting room. +- **Origin Metrics Service**: Allows you to retrieve information about a specific domain. +- **Waiting Room Page**: The endpoint (URL) with the waiting room attached. + +## The VWR Workflow + +During moments of peak traffic, VWRs makes a new page separate from your origin to organize visitors. The VWRs workflow ensures that users are directed to the appropriate origin service while ensuring fairness in the queue and providing metrics and alerts to the administrator. + +1. The Akamai EdgeWorkers check the virtual room service to confirm if a waiting room is set up for an origin service + + - If no waiting room, the EdgeWorker sends the traffic request directly to the origin service. + - If there is a waiting room, the EdgeWorker sends to the waiting room. + +3. The waiting room service adds the request to the waiting room associated with the domain. +4. When a user accesses the waiting room page, the page polls the virtual waiting room service for the latest waiting time and waiting room depth and displays it. +6. When the waiting time is near zero, or the user is at the front of the queue, the waiting room page forwards the user to the origin service. +7. After releasing the request, the waiting room service removes a request from the queue. +8. If a duplicate request is detected, then the waiting room service checks to see if the user has an active session. + - If yes, then the waiting room service returns the user's position in the queue. + - If no, then the waiting room service creates a new session and adds the request to the appropriate queue. + + +:::note + +- The waiting room service periodically checks the sessions to remove requests for expired sessions from the queues. +- The waiting room service periodically checks the sessions to remove requests for expired sessions from the queues. +- The waiting room service collects the metrics for each domain. +- The administrator can turn customer domains on or off through Configuration APIs. +- VWR uses a queue to serve user requests based on join time. You can configure the queue to be FIFO, random, or lottery based. + +::: diff --git a/docs/photoniq/vwrs/02-get-started-vwrs/get-started-vwrs-web-and-mobile.md b/docs/photoniq/vwrs/02-get-started-vwrs/get-started-vwrs-web-and-mobile.md new file mode 100644 index 0000000000..3431c4161c --- /dev/null +++ b/docs/photoniq/vwrs/02-get-started-vwrs/get-started-vwrs-web-and-mobile.md @@ -0,0 +1,85 @@ +--- +sidebar_position: 10 +title: Integrating VWRs on Web and Mobile +--- + +Different types of applications require distinct approaches for integrating with Virtual Waiting Rooms (VWRs) as the applications' platform and user interaction models determine the integration process. + +Let's demonstrate how web and mobile applications can effectively integrate and use VWRs to manage traffic and enhance user experiences. + + +## Prerequisites + +Before proceeding, ensure to have the following tasks completed: + +- **Get Credentials and Access**: Creating a waiting room requires authentication with an API key. Contact and work with Macrometa personnel to obtain the necessary credentials to proceed. +- **Determine waiting room needs**: The PhotonIQ VWRs offers numerous features to customize your waiting room needs: + - **Queue types**: Depending on your particular business use case, VWR offers different [queue types](https://www.macrometa.com/docs/photoniq/vwrs/queue-types). For example, the FIFO type queues and dequeues users based on their order of arrival, while the random queue admits users randomly. + - **Required URLs**: Determine the URLs to incorporate the waiting rooms. +- **Gather information**: Gather all the required information, like waiting room details and traffic expectations, to simplify the setup process. + +## Integrating on Web + +Web apps, also called non-native or browser-based apps, are typically web-based and use standard web technologies such as HTML, CSS, and JavaScript. These applications run within web browsers and are the most common types integrated with VWRs. Integrating your web applications with VWRs occurs through web-based configurations, making it easier to implement an effective traffic management solution like VWR. + +This guide explains the steps to connect your web app to VWRs, enhancing your ability to manage high traffic efficiently and maintain a seamless user experience. + +### Steps + +To integrate your virtual waiting room with your web application: + +1. [Create an API Key](https://www.macrometa.com/docs/apiVwrs#/operations/createAPIKey): An API key grants you access to the virtual waiting room service and is essential for all subsequent operations. You can create an API key with the VWRs GUI or via the VWRS API. + +2. [Configure a VWRs EdgeWorker](../03-configuration-and-setup/01-configuring-edgeworkers.md): EdgeWorkers helps manage the waiting room functionality on the Akamai side by directing traffic to the waiting room. This configuration is crucial for handling incoming traffic and directing it appropriately. + +3. [Create and configure your waiting room](index.md): This step allows you to fine-tune how the waiting room operates and integrates with your site. + +## Integrating on Mobile + +Mobile apps, also called native apps or system-specific apps, are developed for specific platforms using platform-specific programming languages. Unlike web-based apps, mobile apps are developed for specific platforms using platform-specific UI frameworks and the application takes on a greater role in managing the user experience during high-traffic periods, including handling the display of waiting times and managing user expectations. Mobile apps require direct API interactions to manage user experiences effectively during high traffic periods. + +### Steps + +1. [Create your API Key](https://www.macrometa.com/docs/apiVwrs#/operations/createAPIKey): Start by creating an API key to access the VWRs system, as this key is essential for all API interactions. + +2. Create and Configure your waiting room + +3. Use the [VWRs API](https://www.macrometa.com/docs/apiVwrs#/) to observe and manage the user's position in the waiting room. This involves making periodic API calls to check the queue status and manage the user experience accordingly. + + - [Get initial position in waiting room](https://www.macrometa.com/docs/apiVwrs#/paths/api-vwr-v1-position-domain_key/get) + - [Get current position in waiting room](https://www.macrometa.com/docs/apiVwrs#/paths/api-vwr-v1-position-domain_key---request_id/get) + +### Pseudo-Code Example + +Here is a pseudo-code example illustrating how a mobile app interacts with the VWR API to manage a user's waiting experience: + +```javascript +// Initial request specifying the waiting room. +let waitingRoom = "shopping"; +let result = GET("/api/vwr/v1/position/" + waitingRoom); + +// Loop while the user is still in the waiting room. +while (result.position > 0) { + // Notify the user of their current position and expected wait time. + notifyUser(result.position, result.waiting_time); + + // Wait for the specified refresh interval before checking the position again. + sleep(result.refresh_interval); + + // Re-check the user's position using the visitor_id received from the initial call. + result = GET("/api/vwr/v1/position/" + waiting_room + "/" + result.visitor_id); +} + +// Proceed with accessing the protected resource once the user is out of the waiting room. +accessResource(); +``` + +## Next Steps + +Once your virtual waiting room is operational, consider monitoring and managing its performance to ensure optimal functionality: + +- **Metrics and Analytics:** Regularly check the [VWRs metrics](../05-monitoring-vwrs/index.md) to assess the performance and effectiveness of your waiting room. +- **Review Usage Patterns:** Analyze usage data to optimize settings and improve user experiences. You can customize your settings to analyze usage statistics at different time intervals: + - [Hourly Usage](https://www.macrometa.com/docs/apiVwrs#/operations/getHourlyUsage) + - [Daily Usage](https://www.macrometa.com/docs/apiVwrs#/operations/getDailyUsage) + - [Monthly Usage](https://www.macrometa.com/docs/apiVwrs#/operations/getMonthlyUsage) diff --git a/docs/photoniq/vwrs/02-get-started-vwrs/index.md b/docs/photoniq/vwrs/02-get-started-vwrs/index.md new file mode 100644 index 0000000000..dfa3156cb8 --- /dev/null +++ b/docs/photoniq/vwrs/02-get-started-vwrs/index.md @@ -0,0 +1,105 @@ +--- +title: Quickstart +--- + + +The Macrometa PhotonIQ Virtual Waiting Room service (VWRs) offers extensive features to manage high-traffic volumes on websites and applications during peak periods like discounts and holiday sales. By implementing VWRs for their websites, businesses can ensure server stability, thus preventing server overload and potential downtime, ensuring service availability and user satisfaction. + +PhotonIQ virtual waiting room service offers two ways to create and use virtual waiting rooms for your website. + +- The VWRS GUI : A friendly, intuitive graphical user interface that allows you to configure, create, and manage your waiting room(s). +- [The PhotonIQ Virtual Waiting Room API](https://www.macrometa.com/docs/apiVwrs#/): A list of available APIs that allows you to [create](https://www.macrometa.com/docs/apiVwrs#/operations/createWaitingRoom), [update](https://www.macrometa.com/docs/apiVwrs#/operations/updateWaitingRoom), [modify](https://www.macrometa.com/docs/apiVwrs#/operations/patchWaitingRoom), and [delete](https://www.macrometa.com/docs/apiVwrs#/operations/deleteWaitingRoom) your virtual waiting room, and retrieve vital waiting room metrics. + +Let's create our first virtual waiting room service with the VWRs GUI to get started. + +## Objectives + +This quickstart will guide you through: + +- Creating and configuring your first VWR with the PhotonIQ VWRS GUI +- Configuring additional waiting room details +- Monitoring and observing the performance of the VWR + +## Creating your Virtual Waiting Room + +### Steps + +To create a waiting room: + +1. Login to the VWRS GUI with your Macrometa credentials. Macrometa provides these credentials after you sign up for the service. +1. Click **Waiting Rooms** from the top nav bar. +1. Click **New Waiting Room**. This opens a pop-up dialog to enter the following details to set up your virtual waiting room. + +- **waitingroom_name:** The name of the waiting room. Names should be without spaces. Replace spaces with hyphens or dashes. +- **waitingroom_url:** The URL that the waiting room needs to sit in front of. All subpaths of this URL are sent to this defined waiting room. For example, /checkout/path1 and /checkout/path2 are both sent to the /checkout waiting room +- **access_type:** The access type defines how the rate limit should be calculated. Different options include: + - **users:** + - The metric service counts the number of unique user requests every second. These are identified by a request ID stored in the encrypted cookie (vwrs-session). + - A rolling history of unique user requests is kept for 60 seconds. + - Rate Calculation Example: If the metric service indicates 480 unique users in the last 60 seconds, then the rate is 8 unique users per second. + - **users_per_period:** + - Behaves the same as the users access type, except the rate_limit is divided over the defined period. + - Rate Calculation Example: If the maximum rate is 100 for 5 seconds, then the rate is 20 users per second. + - **rps:** + - The metric service counts the number of requests to the origin server per second (RPS). + - Rate Calculation Example: If the maximum number of requests allowed is 20 and 13 POST requests are detected, then 7 more requests are released from the waiting room. +- **rate_period:** Must be set if the access_type is users_per_period. + - Defines the time (in seconds) for rate calculation. + - Must be a number greater than zero. +- **rate_limit:** The rate at which traffic should be diverted to the waiting room. + - Must be a number greater than zero. + + Note: **For access_type of users and rps, this is the maximum request rate. For users_per_period, the maximum rate is calculated using the active rate divided by the period** + +- **max_origin_usage_time**: The time (in seconds) that users can access the origin after being granted access. After this period, users are forwarded to the waiting room again. +- **waiting_room_interval**: Defined in seconds, this interval determines how often the waiting room HTML page is updated with information like the request's position, estimated waiting time, and the maximum number of requests in the waiting room. + + +![create virtual waiting room](/img/photoniq/vwr/create-vwr.png) + +4. Click **Add Waiting Room** + +### Configuring Additional Waiting Room Fields + +The Virtual waiting room service allows you to further define and guide the behavior of your waiting room with its **Advanced Settings** fields. These fields include the queue type, dequeue mode, and others. + +1. Click **Advanced Settings** from the waiting room definition page + +![Configure VWR behavior](/img/photoniq/vwr/configure-additional-details.png) + +2. Configure these additional details: + +![additional details](/img/photoniq/vwr/addvanced-settings.png) + +- **queue_type**: Defines how requests should be removed from the waiting room. The three possible queue types are fifo, random, and lottery. If this is not set, then the default queue is fifo. +- **queue_mode**: You can configure the waiting room to be enabled dynamically. When set to auto, the waiting room is enabled after reaching the defined rate_limit for a specific metric_interval. If set to manual, then the waiting room is always enabled. +- **dequeue_mode**: When the value is on, users in the waiting room are granted access to the origin at a rate given by rate_limit. When the value is off, users remain in the waiting room indefinitely. +- **metric_interval**: The time (in seconds) to enable and disable the waiting room. It represents how long the traffic must be at or above the rate limit before being directed to the waiting room. +- **waiting_room_path**: The cloud origin (such as NetStorage) path that stores the HTML for the waiting room. The path should be a fully qualified path like /{upload-directory-id}/path. +- **request_priority**: An array of priorities, where the highest priority corresponds to the lowest number. + +3. Click **Add Waiting Room** + +Our waiting room is now available. + +![waiting room](/img/photoniq/vwr/kinky-vwr.png) + +## Monitoring your Virtual Waiting Room + +PhotonIQ VWRs allows you to view and manage your virtual waiting rooms via its GUI dashboard or the [VWRs metrics API](https://www.macrometa.com/docs/apiVwrs#/operations/getMetrics). + +For monitoring the activity of your virtual waiting rooms using the dashboard: + +1. Go to **Activity** on your VWRs dashboard. +1. Select the name of the waiting room and time duration for which you intend to monitor activity. + +![Activity tab](/img/photoniq/vwr/activity-tab.png) + +The activity tab allows you to view metrics like: + +- Users in Queue +- Average Wait Time +- Success Rate +- Queue Abandonment + +By observing these metrics, you can test changes to your waiting room to see how it affects the metrics. For example, [customizing your virtual waiting room](./customize-waitroom.md) to observe how it affects queue abandonment. diff --git a/docs/photoniq/vwrs/03-configuration-and-setup/01-configuring-edgeworkers.md b/docs/photoniq/vwrs/03-configuration-and-setup/01-configuring-edgeworkers.md new file mode 100644 index 0000000000..56bbef235b --- /dev/null +++ b/docs/photoniq/vwrs/03-configuration-and-setup/01-configuring-edgeworkers.md @@ -0,0 +1,126 @@ +--- +sidebar_position: 30 +title: Configure a VWRs EdgeWorker +--- + +# Overview + +VWRs require [Akamai EdgeWorker Documentation](https://techdocs.akamai.com/edgeworkers/docs) to execute functions at the edge to help redirect and optimize web traffic for your websites. To get started using EdgeWorkers with VWRs, you need to import the `VirtualWaitingRoom` class from the photoniq-vwrs-client using Node Package Manager (NPM). This integrates the VWRs with the EdgeWorker. + +## Setting Up EdgeWorkers + +### Prerequisites +To configure EdgeWorkers for use with VWRs, you need the following: + +- An [Akamai EdgeWorker resource tier](https://techdocs.akamai.com/edgeworkers/docs/resource-tier-limitations): Because the VWRs EdgeWorker performs up to two sub-requests, this resource tier must allow at least two HTTP sub-requests on the `onClientRequest` event handler. +- [Akamai Property Manager user-defined variables](https://techdocs.akamai.com/edgeworkers/docs/request-object#setvariable): This helps set the value of the Property Manager user-defined variable to control how Akamai controls network traffic. PhotonIQ uses about 350 characters out of the 1024 limit set by Akamai. + +### Step 1: Install the PhotonIQ VWRs Client + +Before you can set up an EdgeWorker, you must install `@macrometa/photoniq-vwrs-client`. + +1. To set the authentication token, open your terminal and execute the following command. This command configures npm to use the specified authentication token when interacting with the npm registry. Make sure you replace with your actual read key: + Now, you are ready to install the private package. Npm uses the previously set authentication token to authenticate and download the package. In your terminal, run the following command: + +```bash +npm install @macrometa/photoniq-vwrs-client +``` + +2. After the package installation is complete, verify its presence. Check your project’s node_modules directory to ensure that `@macrometa/photoniq-vwrs-client` has been successfully installed. + +:::note +If you encounter a _404 Not Found error_ when trying to install `@macrometa/photoniq-vwrs-client`, then check your .npmrc file to ensure that it has a valid registry set and the valid token is set. This file should contain the correct configuration for accessing npm packages. +::: + +### Step 2: Configuring Options +After installing the VWRs client, you need to configure some options. While some of these options are mandatory, others are optional. + +#### Mandatory Configuration Options + +The following configuration options must be set: + +- **apiKey**: Use the [VWRs authorization key API](https://www.macrometa.com/docs/apiVwrs#/operations/createAPIKey) to create this key. +- **vwrsMetricHost**: The host for the VWRs metric service. +- **vwrsHost:**The host for the VWRs service. +- **digestKey**: The digest key verifies the integrity of the data stored in the cookie. Please use a 128-bit or 256-bit key. For example, you can generate a key using the command `openssl rand -hex 16`. +- **encryptionKey**: This key encrypts the waiting room data stored in the cookie. The key must be either 128 or 256 bits long. For example, you can generate a key using the command `openssl rand -hex 16`. + +#### Optional Configuration Options + +The following configuration options are optional: + +- **isFailOpen**: Has a default value set to `true`, which forwards request to the origin server if an error occurs. However, with a `false` value, an occurrence of error displays an error message. +- **originAccessMode**: This option determines how long access is granted to the origin server (default: `ORIGIN_USAGE_TIME`): + - **ORIGIN_USAGE_TIME**: The access time, defined for each domain (`max_origin_usage_time`), remains fixed. Once a user is granted access to the origin, they can only access it for the duration specified in the `max_origin_usage_time` field. + - **ORIGIN_IDLE_TIME:** The access time, defined for each domain, increases by the number of seconds specified in the `max_origin_usage_time` field. Each time this domain is accessed, the access time is extended accordingly. This behaves similarly to an abandonment timeout, where the session is abandoned if the request has been idle for the `max_origin_usage_time` time. +- **statusConfigLimits**: This defines the waiting room information that is returned by the status call. Use the following three values to define what the status page returns: + - **avgWaitingTime**: If set to `true`, then the average waiting time is returned by the status call. (default: `true`) + - **qDepth**: If set to `true`, then the waiting room queue size is returned. (default: `true`) + - **position**: If set to `true`, then the position of the request in the waiting room queue is returned. (default: `true`) + +#### Request Configuration + +A request configuration is an optional object that contains configuration parameters for the request handler. Options include: + +- **waitingRoomPath**: The cloud origin (such as NetStorage) path to the waiting room HTML. +- **extraFingerprint**: Additional data to include in the fingerprint calculation. +- **debugMode**: This flag enables debug mode. In debug mode, the unencrypted cookie is stored in the `x-vwrs-debug` header and logged to the logger (default: `false`). +- **priority:** A positive whole number indicates the priority of the request when a priority queue is enabled for the specific waiting room. This priority number must be one of the priorities configured for the waiting room. + + +## EdgeWorker Example + +An example of `main.js` in an EdgeWorker bundle: + +```js +import { logger } from "log"; +import VirtualWaitingRoom from "./library/virtualWaitingRoom.js"; + +const virtualWaitingRoomConfiguration = new VirtualWaitingRoom({ + apiKey: "YourAPIKey", + digestKey: "YourVwrsDigestKey", + encryptionKey: "YourVwrsEncryptionKey", + vwrsMetricHost: "api-demo-vwr-metrics.paas.macrometa.io", + vwrsHost: "api-demo-vwr.paas.macrometa.io", + isFailOpen: "true", + originAccessMode: "ORIGIN_USAGE_TIME", + statusConfigLimits: { + avgWaitingTime: true, + qDepth: true, + Position: true, + }, +}); + +export async function onClientRequest(request) { + const reqOptions = { + waitingRoomPath: "/1473985/doc.html", + debugMode: true, + extraFingerprint: [request.getVariable("PMUSER_TFDH")], + }; + + const result = await virtualWaitingRoomConfiguration.handleVwrsRequest( + request, + reqOptions + ); + if (result.waitingRoom) { + // Request sent to waiting room + } +} + +export async function onClientResponse(request, response) { + const reqOptions = { + debugMode: true, + extraFingerprint: [request.getVariable("PMUSER_TFDH")], + }; + + const result = await virtualWaitingRoomConfiguration.handleVwrsResponse( + request, + response, + reqOptions + ); + if (result.waitingRoom) { + // Request sent to waiting room + } +} +``` + diff --git a/docs/photoniq/vwrs/configure-waiting-rooms.md b/docs/photoniq/vwrs/03-configuration-and-setup/02-configure-waiting-rooms.md similarity index 60% rename from docs/photoniq/vwrs/configure-waiting-rooms.md rename to docs/photoniq/vwrs/03-configuration-and-setup/02-configure-waiting-rooms.md index b86c9a178b..292ad6c967 100644 --- a/docs/photoniq/vwrs/configure-waiting-rooms.md +++ b/docs/photoniq/vwrs/03-configuration-and-setup/02-configure-waiting-rooms.md @@ -1,25 +1,29 @@ --- sidebar_position: 20 -title: Configuring Waiting Rooms +title: Configure Waiting Room Parameters --- -This page explains what can be configured in each waiting room using API endpoint properties. For more information about how to create a waiting room, refer to [Configure a Domain](configure-domain.md). +This page explains some parameters to configure when using the VWR using API endpoint properties. These include configurations when: + +- Entering the waiting room +- In the waiting room +- Exiting the waiting room ## Entering the Waiting Room - **Rate Limit:** Set the rate (maximum users per second) at which traffic should be diverted to the waiting room. (`rate_limit` property) -- **Waiting Room Path:** The URL that the waiting room needs to sit in front of. (`domain_url` property) +- **Waiting Room Path:** The URL that sits in front of the waiting room (`domain_url` property) - **Queue Type:** Defines how requests should be removed from the waiting room, such as FIFO (first in, first out). (`queue_type` property) ## In the Waiting Room -- **Waiting Room HTML:** UI that is shown to users in the waiting room. (`waiting_room_path` property) -- **Waiting Room Position and Time (in HTML):** Include any of the position or time in the waiting room UI. (Configured in the [Akamai EdgeWorker](configure-vwrs-edgeworker.md).) +- **Waiting Room HTML:** UI shown to users in the waiting room. (`waiting_room_path` property) +- **Waiting Room Position and Time (in HTML):** Include any of the position or time in the waiting room UI. This is (Configured in the [Akamai EdgeWorker](01-configuring-edgeworkers.md) - **Waiting Room HTMl Refresh Interval:** How often waiting room UI should be refreshed in the user's browser. (`waiting_room_interval` property) ## Exiting the Waiting Room - **Max Origin Usage Time:** The amount of time that users can access the origin after being granted access. (`max_origin_usage_time` property) -- **Access Type:** Choose one of the following options. (Configured in the [Akamai EdgeWorker](configure-vwrs-edgeworker.md).) +- **Access Type:** Choose one of the following options when [configuring the Akamai EdgeWorker](01-configuring-edgeworkers.md) - Following the access duration period (set in the `max_origin_usage_time` property), the user is redirected to the waiting room. - The user is redirected to the waiting room if there is no activity for the duration of the access duration period (set in the `max_origin_usage_time` property). diff --git a/docs/photoniq/vwrs/waitingroom.md b/docs/photoniq/vwrs/03-configuration-and-setup/03-configure-vwrs-waitingroom-page.md similarity index 79% rename from docs/photoniq/vwrs/waitingroom.md rename to docs/photoniq/vwrs/03-configuration-and-setup/03-configure-vwrs-waitingroom-page.md index ae393a92ee..b496ff63fe 100644 --- a/docs/photoniq/vwrs/waitingroom.md +++ b/docs/photoniq/vwrs/03-configuration-and-setup/03-configure-vwrs-waitingroom-page.md @@ -1,9 +1,15 @@ --- -title: Waiting Room HTML page +sidebar_position: 30 +title: Explore the VWRs Waiting Room Page --- -Below is a sample HTML template for a waiting room page. This page is displayed to users who are redirected to the waiting room. It's fully customizable to suit your needs. Within the template, the class attributes `queue-position`, `queue-depth`, and `avg-wait-time` are used to display the visitor's current position in the queue, the total number of users in the waiting room, and the average waiting time, respectively. +The VWRs waiting room page is a customizable HTML page that users see when they are directed to the waiting room. The waiting room page is hosted on the Akamai NetStorage and configured using the `waitingRoomPath` option in the VWRs EdgeWorker `handleVwrsRequest()` function. +Here is an example of such a page: + +![Waiting Room Page](../../../../static/img/photoniq/vwr/vwr-activity.jpg) + +Below is the template code for the page: ```html @@ -212,3 +218,28 @@ Below is a sample HTML template for a waiting room page. This page is displayed ``` + +Within the above template, the class attributes `queue-position`, `queue-depth`, and `avg-wait-time` displays the visitor's current position in the queue, the total number of users in the waiting room, and the average waiting time, respectively. + +## Configuring the Waiting Room Page + +The waiting room path must be configured as a [Conditional Origin](https://techdocs.akamai.com/property-mgr/docs/conditional-origins) in Akamai's property manager. This allows the waiting room HTML page to be served from the Akamai NetStorage. + +Configure the conditional origin with the following settings: + +- Set the Origin ID to `waitingroom`. + +In the behaviors section: + + **Origin Server**: + + - Set the Origin type to Netstorage. + - Set the NetStorage Account to the appropriate account. + + **Caching**: + + - Caching option: cache + - Force revalidation of stale objects: Always revalidate the origin + - Maxage: 10 minutes + +![Waiting Room Page](../../../../static/img/photoniq/vwr/akamai-cond-origin.png) diff --git a/docs/photoniq/vwrs/03-configuration-and-setup/04-customizing-vwrs.md b/docs/photoniq/vwrs/03-configuration-and-setup/04-customizing-vwrs.md new file mode 100644 index 0000000000..19f9e9302c --- /dev/null +++ b/docs/photoniq/vwrs/03-configuration-and-setup/04-customizing-vwrs.md @@ -0,0 +1,97 @@ +--- +sidebar_position: 30 +title: Customizing VWRs +--- + +## Fingerprinting + +VWRs can use device fingerprinting techniques to help mitigate cookie sharing and replay attacks. By default, a basic fingerprint is generated using information derived from the device object ([https://techdocs.akamai.com/edgeworkers/docs/device-object](https://techdocs.akamai.com/edgeworkers/docs/device-object)). If stronger device fingerprinting is required, then you can override this logic with your own, or configure it to use one of the fingerprinting techniques available in Akamai’s security products. + +## Priority + +VWRS allows you customize a waiting room with up to ten priorities, with these priority numbers being positive integers from 1 through 255. + +### Configuring Priority + +Configure the priorities using the `POST/PUT/PATCH /api/vwr/v1/domains` REST API. + +For instance, to configure three priorities with values of 1, 20, and 255, use the `PATCH /api/vwr/v1/domains` REST API to update the domain: + +```bash +curl -X 'PATCH' \ + https://api-vwr-service.gdn-akamai.com/api/vwr/v1/origins/example3.com \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'authorization: test_key.12345678abcdefghijklABCDEFGHIJKL' \ + -d '{ + "priority": [1, 20, 255] +}' +``` + +### Implementing Priority +After configuring priorities, you can implement it to prioritize traffic in your waiting room. +To prioritize the traffic, you must pass the priority to the `handleVwrsRequest()` and `handleVwrsResponse()` functions. + +Here's a template demonstrating how to include a priority with the request in the `handleVwrsRequest()` call: + +```js +export async function onClientRequest(request: EW.IngressClientRequest) { + await client.handleVwrsRequest(request, { priority: 1 }); +} +``` + +This template sets the priority of this request to 1. + +### Retrieving Priority + +VWRs offers several methods to retrieve the actual priority. These methods include query parameters, headers, or cookies. Selecting a method depends on the specific implementation needs of the application. + +#### Query Parameter Example + +```bash +GET /checkout?waiting-room-priority=20 +``` + +The example adds the request to the waiting room with a priority of 20. + +```js +export async function onClientRequest(request: EW.IngressClientRequest) { + const queryParams = new URLSearchParams(request.query); + const reqPriority = parseInt(queryParams.get("waiting-room-priority"), 10); + await client.handleVwrsRequest(request, { priority: reqPriority }); +} +``` + +#### HTTP Header Example + +```bash +GET /checkout +x-waiting-room-priority: 20 +``` + +The example adds the request to the waiting room with a priority of 20. + +```js +export async function onClientRequest(request: EW.IngressClientRequest) { + const reqPriorityStr = request.getHeader("x-waiting-room-priority")[0]; + Const reqPriority = parseInt(reqPriorityStr, 10); + await client.handleVwrsRequest(request, {priority: reqPriority}); +} +``` + +### HTTP Cookie Example + +```bash +GET /checkout +Cookie: waiting-room-priority=20 +``` + +The example adds the request to the waiting room with a priority of 20. + +```bash +export async function onClientRequest(request: EW.IngressClientRequest) { + const cookies = new Cookies(request.getHeader("Cookie")); + const reqPriority = parseInt(cookies.get("waiting-room-priority"), 10); + await client.handleVwrsRequest(request, {priority: reqPriority}); +} +``` \ No newline at end of file diff --git a/docs/photoniq/vwrs/03-configuration-and-setup/index.md b/docs/photoniq/vwrs/03-configuration-and-setup/index.md new file mode 100644 index 0000000000..d63c4dbd04 --- /dev/null +++ b/docs/photoniq/vwrs/03-configuration-and-setup/index.md @@ -0,0 +1,6 @@ +--- +title: Configuration and Set Up +--- + + + diff --git a/docs/photoniq/vwrs/04-queue-types.md b/docs/photoniq/vwrs/04-queue-types.md new file mode 100644 index 0000000000..383b076004 --- /dev/null +++ b/docs/photoniq/vwrs/04-queue-types.md @@ -0,0 +1,24 @@ +--- +sidebar_position: 25 +title: VWRs Queues +--- + +This page describes the different types of queues supported by Virtual Waiting Rooms. + +## FIFO + +This FIFO (first in, first out) queue operates on a "first come, first served" basis. Every new request pushes older requests to the front of the queue, closer to the origin server. Thus, when the system removes a request from the front, all subsequent elements move up one position. + +### Use cases for FIFO Queues + +## Random + +The random queuing approach selects requests at random, without a criteria, preference or priority. Here, every request in the queue has an equal possibility for processing. This method is beneficial when prioritizing requests based on their arrival time or other criteria. Introducing a random element can disperse the processing load. + +### Use cases for Random Queues + +## Lottery + +The lottery queuing approach uses assigned priorities and is an advanced method of selecting requests from a queue. This method gives each request a priority or weight, representing its probability of selection for processing. When removing a request, the system conducts a "lottery" to choose the winning request based on its assigned priority. This approach enables you to prioritize specific requests by giving them a higher priority, increasing their likelihood of being selected for processing. + +### Use cases for Lottery Queues diff --git a/docs/photoniq/vwrs/05-monitoring-vwrs/index.md b/docs/photoniq/vwrs/05-monitoring-vwrs/index.md new file mode 100644 index 0000000000..120f241db9 --- /dev/null +++ b/docs/photoniq/vwrs/05-monitoring-vwrs/index.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 100 +title: Get VWRs Metrics +--- + +## Overview + +Macrometa PhotonIQ Virtual Waiting Rooms (VWRs) has built-in metrics that allow you to retrieve waiting room telemetry per waiting room, per minute. This data has a shelf life of 90days. + +VWRs metrics allow you to: + +- Evaluate peak traffic flow through your waiting room and onto your site. +- Determine how long users spent in the waiting room. +- Use analytics to assess and adjust your waiting room settings. + + +## Available Metrics + +The metrics response body includes the following properties: + +- **avg_waiting_time**: The average time users spend in the virtual waiting room before being granted access to the origin service (in milliseconds). +- **domain_key**: The domain key. +- **duplicate_request_rate**: The percentage of duplicate requests detected and managed by the virtual waiting room service. +- **origin_key**: The origin key. +- **peak_queue_length**: The highest number of users in the queue during a specific period. +- **queue_abandonment_rate**: The percentage of users who leave the virtual waiting room without accessing the origin service. +- **request_success_rate**: The percentage of requests to the origin service that are successfully processed after users leave the virtual waiting room. +- **timestamp**: The epoch time of the start interval when the metric was generated (in seconds). + diff --git a/docs/photoniq/vwrs/vwrs-metrics.md b/docs/photoniq/vwrs/05-monitoring-vwrs/retrieve-metrics.md similarity index 53% rename from docs/photoniq/vwrs/vwrs-metrics.md rename to docs/photoniq/vwrs/05-monitoring-vwrs/retrieve-metrics.md index 446103805e..61fb32cd5b 100644 --- a/docs/photoniq/vwrs/vwrs-metrics.md +++ b/docs/photoniq/vwrs/05-monitoring-vwrs/retrieve-metrics.md @@ -1,38 +1,19 @@ --- -sidebar_position: 100 -title: Get VWRs Metrics +title: Retrieve Sample Metrics --- -Macrometa PhotonIQ Virtual Waiting Rooms (VWRs) has built-in metrics that allow you to retrieve waiting room telemetry per waiting room, per minute. Data is stored for the past 90 days. - -Using VWRs metrics, you can: - -- Evaluate peak traffic flow through your waiting room and onto your site. -- Determine how long users spent in the waiting room. -- Use analytics to help calibrate your waiting room settings. - ## Get Metrics -You can retrieve metrics using the following endpoints: +VWRs offers different endpoint for retrieving your waiting room metrics: - [Get Metrics for a Domain](https://www.macrometa.com/docs/apiVwrs#/operations/getMetrics) - Retrieve the metrics for a specific domain. Set start and end times to get metrics for a specific time period. To get the domain key, use the [Get Information for All Domains](https://www.macrometa.com/docs/apiVwrs#/operations/getDomainUsingQueryParams) endpoint. - [Get All Metrics](https://www.macrometa.com/docs/apiVwrs#/operations/filterMetricsByDate) - Retrieve metrics for all domains. Set start and end times to get metrics for a specific time period. -## Available Metrics - -The metrics response body includes the following properties: - -- **avg_waiting_time**: The average time users spend in the virtual waiting room before being granted access to the origin service (in milliseconds). -- **domain_key**: The domain key. -- **duplicate_request_rate**: The percentage of duplicate requests detected and managed by the virtual waiting room service. -- **origin_key**: The origin key. -- **peak_queue_length**: The highest number of users in the queue during a specific period. -- **queue_abandonment_rate**: The percentage of users who leave the virtual waiting room without accessing the origin service. -- **request_success_rate**: The percentage of requests to the origin service that are successfully processed after users leave the virtual waiting room. -- **timestamp**: The epoch time of the start interval when the metric was generated (in seconds). ## Example Response +Below is a sample response: + ```json [ { diff --git a/docs/photoniq/vwrs/06-vwrs-best-practices.md b/docs/photoniq/vwrs/06-vwrs-best-practices.md new file mode 100644 index 0000000000..1f1dd269ce --- /dev/null +++ b/docs/photoniq/vwrs/06-vwrs-best-practices.md @@ -0,0 +1,14 @@ +--- +sidebar_position: 110 +title: Best Practices for using VWRs +--- + +This page provides information on best practices for using Macrometa PhotonIQ Virtual Waiting Rooms (VWRs). + +## Refresh Interval + +When configuring refresh interval on mobile applications, consider its impact on mobile device battery life and data usage as frequent updates increase both consumption metrics. + +## UI Responsiveness + +Take advantage of PhotonIQ's asynchronous network calls to make your REST API calls when updating your waiting room. These low-latency calls ensures your application remains responsive with information displaying correctly, ensuring pleasant user experience. diff --git a/docs/photoniq/vwrs/vwrs-status-codes.md b/docs/photoniq/vwrs/07-troubleshooting/02-vwrs-status-codes.md similarity index 100% rename from docs/photoniq/vwrs/vwrs-status-codes.md rename to docs/photoniq/vwrs/07-troubleshooting/02-vwrs-status-codes.md diff --git a/docs/photoniq/vwrs/troubleshoot-vwrs.md b/docs/photoniq/vwrs/07-troubleshooting/index.md similarity index 54% rename from docs/photoniq/vwrs/troubleshoot-vwrs.md rename to docs/photoniq/vwrs/07-troubleshooting/index.md index f3f03c0626..2b3f8a3769 100644 --- a/docs/photoniq/vwrs/troubleshoot-vwrs.md +++ b/docs/photoniq/vwrs/07-troubleshooting/index.md @@ -3,19 +3,27 @@ sidebar_position: 120 title: Troubleshoot VWRs --- -This page provides troubleshooting information for Macrometa PhotonIQ Virtual Waiting Rooms (VWRs). +When configuring and setting your VWR, some errors may occur from misconfigurations in the waiting room html code, domain url, or the EdgeWorker. -## No Waiting Room Configured +Let's explore some of these errors and ways to troubleshoot these errors. -If a waiting room has not been configured, then the waiting room library returns the header _No-Waiting-Room_. This means that the domain URL is not configured correctly. + +## Waiting Room Misconfigurations + +This returns the header response `_No-Waiting-Room_`, and points towards a domain URL misconfiguration. Fixing this requires checking your domain URL for any misspellings or errors. ## Troubleshoot Waiting Room HTML -You have the option to set the URL for the waiting room HTML template either via the library or the domain record. To get a preview of the waiting room HTML template, launch your preferred web browser and go to the following URL: `https:///waiting-room-path>/preview`. For example, `http://show.store.com/checkout/preview`. +Preview your waiting room HTML template by launching your preferred web browser and navigating to your domain URL. + +Sample URL format: `https:///waiting-room-path>/preview` + +For example: `http://show.store.com/checkout/preview` + View the waiting room HTML page and make changes when needed. ## Troubleshoot Waiting Room Cookie -The `vwrs-cookie` cookie holds valuable information regarding each user's access to the waiting room. If you need to debug and access the content of the cookie, then you can enable debugging mode when calling the `handleVwrsRequest()` function. Enabling debugging mode stores the unencrypted cookie in the `x-vwrs-debug` header, granting you access to its content for debugging purposes. +The `vwrs-cookie` cookie holds valuable information regarding each user's access to the waiting room. Debugging and accessing the cookie content requires enabling debugging mode when calling the `handleVwrsRequest()` function. Enabling debugging mode stores the unencrypted cookie in the `x-vwrs-debug` header, granting you access to its content for debugging purposes. ```js export async function onClientRequest(request) { @@ -39,14 +47,13 @@ export async function onClientResponse(request, response) { ## VWRs EdgeWorker Exceeding PM_USER Space -The VWRs EdgeWorker uses Akamai's Property Manager user-defined variables. The maximum limit supported by Akamai EdgeWorkers is 1024 characters. If this limit is exceeded, the -following error message is displayed by the library code: `Setting metadata variable would exceed total variable size limit`. +The VWRs EdgeWorker uses Akamai's Property Manager user-defined variables. The maximum limit supported by Akamai EdgeWorkers is 1024 characters. Exceeding this limits causes the library code to display the following error message: `Setting metadata variable would exceed total variable size limit`. ## Report Status Codes When running library code, the library provides status codes to inform users about limitations and issues in the form of four-letter codes. These status codes are stored in the PMUSER_VWRS_STATUS_CODE variable. -For a comprehensive list of the meaning behind each four-letter code, refer to [VWRs Status Codes](vwrs-status-codes.md). +For a comprehensive list of the meaning behind each four-letter code, refer to [VWRs Status Codes](02-vwrs-status-codes.md). ## Request-Level Debugging diff --git a/docs/photoniq/vwrs/configure-domain.md b/docs/photoniq/vwrs/configure-domain.md deleted file mode 100644 index 3c1e6d88da..0000000000 --- a/docs/photoniq/vwrs/configure-domain.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 30 -title: Configure a Domain ---- - -You can configure a domain with the [Create a Domain REST API](https://www.macrometa.com/docs/apiVwrs#/operations/createDomain). Use this API to define and configure the behavior of the waiting room. - -## Domain Definition Fields - -The following required fields define a domain (waiting room): - -- **domain_key**: The unique key of the domain. -- **domain_url**: The URL that the waiting room needs to sit in front of. All subpaths of this URL are sent to this defined waiting room. For example, `/checkout/path1` and `/checkout/path2` are both sent to the `/checkout` waiting room. -- **access_type**: The access type defines how the rate limit should be calculated. Different options include: - - **users**: - - The metric service counts the number of unique user requests every second. These are identified by a request ID stored in the encrypted cookie (`vwrs-session`). - - A rolling history of unique user requests is kept for 60 seconds. - - **Rate Calculation Example**: If the metric service indicates 480 unique users in the last 60 seconds, then the rate is 8 unique users per second. - - - **users_per_period**: - - Behaves the same as the `users` access type, except the `rate_limit` is divided over the defined period. - - **Rate Calculation Example**: If the maximum rate is 100 for 5 seconds, then the rate is 20 users per second. - - - **rps**: - - The metric service counts the number of requests to the origin server per second (RPS). - - **Rate Calculation Example**: If the maximum number of requests allowed is 20 and 13 POST requests are detected, then 7 more requests are released from the waiting room. - -- **rate_period**: Must be set if the `access_type` is `users_per_period`. - - Defines the time (in seconds) for rate calculation. - - Must be a number greater than zero. - -- **rate_limit**: The rate at which traffic should be diverted to the waiting room. - - Must be a number greater than zero. - - **Note**: For `access_type` of `users` and `rps`, this is the maximum request rate. For `users_per_period`, the maximum rate is calculated using the active rate divided by the period. - -## Domain Behavior Fields - -The following optional fields define the behavior of the waiting room: - -- **queue_type**: Defines how requests should be removed from the waiting room. The three possible queue types are `fifo`, `random`, and `lottery`. If this is not set, then the default queue is `fifo`. -- **queue_mode**: You can configure the waiting room to be enabled dynamically. When set to `auto`, the waiting room is enabled after reaching the defined `rate_limit` for a specific `metric_interval`. If set to `manual`, then the waiting room is always enabled. -- **dequeue_mode**: When the value is `on`, users in the waiting room are granted access to the origin at a rate given by `rate_limit`. When the value is `off`, users remain in the waiting room indefinitely. -- **metric_interval**: The time (in seconds) to enable and disable the waiting room. It represents how long the traffic must be at or above the rate limit before being directed to the waiting room. -- **max_origin_usage_time**: The time (in seconds) that users can access the origin after being granted access. After this period, users are forwarded to the waiting room again. -- **waiting_room_interval**: Defined in seconds, this interval determines how often the waiting room HTML page is updated with information like the request's position, estimated waiting time, and the maximum number of requests in the waiting room. -- **waiting_room_path**: The cloud origin (such as NetStorage) path for a domain that stores the HTML for the waiting room. The path should be a fully qualified path like `/{upload-directory-id}/path`. -- **request_priority**: An array of priorities, where the highest priority corresponds to the lowest number. diff --git a/docs/photoniq/vwrs/configure-vwrs-edgeworker.md b/docs/photoniq/vwrs/configure-vwrs-edgeworker.md deleted file mode 100644 index 78dce26b8c..0000000000 --- a/docs/photoniq/vwrs/configure-vwrs-edgeworker.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_position: 30 -title: Configure a VWRs EdgeWorker ---- - -In the EdgeWorker, import the `VirtualWaitingRoom` class from the photoniq-vwrs-client using Node Package Manager (NPM). This integrates the VWRs with the EdgeWorker. For more information about Akamai EdgeWorkers, refer to [Akamai EdgeWorker Documentation](https://techdocs.akamai.com/edgeworkers/docs). - -## EdgeWorker Requirements - -- The VWRs EdgeWorker performs up to two sub-requests. Therefore, an Akamai EdgeWorker resource tier that allows at least two HTTP sub-requests on the onClientRequest event handler is needed. Refer to the [Akamai Resource tie limitations](https://techdocs.akamai.com/edgeworkers/docs/resource-tier-limitations) page for more information. - -- The VWRs EdgeWorker uses Akamai's Property Manager user-defined variables. The maximum limit supported by Akamai EdgeWorkers is 1024 characters. VWRs uses about 350 of those characters. Refer to Akamai's [Request Object API](https://techdocs.akamai.com/edgeworkers/docs/request-object#setvariable) for more information. - -## Install the PhotonIQ VWRs Client - -Before you can set up an EdgeWorker, you must install `@macrometa/photoniq-vwrs-client`. - -1. To set the authentication token, open your terminal and execute the following command. This command configures npm to use the specified authentication token when interacting with the npm registry. Make sure you replace with your actual read key: - Now, you are ready to install the private package. Npm uses the previously set authentication token to authenticate and download the package. In your terminal, run the following command: - -```bash -npm install @macrometa/photoniq-vwrs-client -``` - -2. After the package installation is complete, verify its presence. Check your project’s node_modules directory to ensure that `@macrometa/photoniq-vwrs-client` has been successfully installed. - -:::note -If you encounter a _404 Not Found error_ when trying to install `@macrometa/photoniq-vwrs-client`, then check your .npmrc file to ensure that it has a valid registry set and the valid token is set. This file should contain the correct configuration for accessing npm packages. -::: - -## Mandatory Configuration Options - -The following configuration options must be set: - -- **apiKey**: This API Key is generated using the VWRs authorization key API. Please refer to the documentation for `POST /api/vwr/v1/apikey` on how to create this key. -- **vwrsMetricHost**: The host for the VWRs metric service. -- **vwrsHost:**The host for the VWRs service. -- **digestKey**: The digest key is used to verify the integrity of the data stored in the cookie. Please use a 128-bit or 256-bit key. For example, you can generate a key using the command `openssl rand -hex 16`. -- **encryptionKey**: This key is used to encrypt the waiting room data stored in the cookie. The key must be either 128 or 256 bits long. For example, you can generate a key using the command `openssl rand -hex 16`. - -The following configuration options are optional: - -- **isFailOpen**: When set to `true` (fail open) and an error occurs, the request is forwarded to the origin. An error message is displayed when set to `false` (fail close) and an error occurs. (default: `true`). -- **originAccessMode**: This option determines how long access is granted to the origin server (default: `ORIGIN_USAGE_TIME`): - - **ORIGIN_USAGE_TIME**: The access time, defined for each domain (`max_origin_usage_time`), remains fixed. Once a user is granted access to the origin, they can only access it for the duration specified in the `max_origin_usage_time` field. - - **ORIGIN_IDLE_TIME:** The access time, defined for each domain, increases by the number of seconds specified in the `max_origin_usage_time` field. Each time this domain is accessed, the access time is extended accordingly. This behaves similarly to an abandonment timeout, where the session is abandoned if the request has been idle for the `max_origin_usage_time` time. -- **statusConfigLimits**: This defines the waiting room information that is returned by the status call. Use the following three values to define what the status page returns: - - **avgWaitingTime**: If set to `true`, then the average waiting time is returned by the status call. (default: `true`) - - **qDepth**: If set to `true`, then the waiting room queue size is returned. (default: `true`) - - **position**: If set to `true`, then the position of the request in the waiting room queue is returned. (default: `true`) - -## Request Configuration - -A request configuration is an optional object that contains configuration parameters for the request handler. Options include: - -- **waitingRoomPath**: The cloud origin (such as NetStorage) path to the waiting room HTML. -- **extraFingerprint**: Additional data to include in the fingerprint calculation. -- **debugMode**: This flag enables debug mode. In debug mode, the unencrypted cookie is stored in the `x-vwrs-debug` header and logged to the logger (default: `false`). -- **priority:** A positive whole number indicates the priority of the request when a priority queue is enabled for the specific waiting room. This priority number must be one of the priorities configured for the waiting room. - -## Fingerprinting - -VWRs can use device fingerprinting techniques to help mitigate cookie sharing and replay attacks. By default, a basic fingerprint is generated using information derived from the device object ([https://techdocs.akamai.com/edgeworkers/docs/device-object](https://techdocs.akamai.com/edgeworkers/docs/device-object)). If stronger device fingerprinting is required, then you can override this logic with your own, or configure it to use one of the fingerprinting techniques available in Akamai’s security products. - -## Priority - -You can customize a waiting room with up to ten priorities, the priorities being positive numbers from 1 through 255. Configure the priorities using the `POST/PUT/PATCH /api/vwr/v1/domains` REST API. - -For instance, consider configuring three priorities with values of 1, 20, and 255. To accomplish this, you can use the `PATCH /api/vwr/v1/domains` REST API to update the domain: - -```bash -curl -X 'PATCH' \ - https://api-vwr-service.gdn-akamai.com/api/vwr/v1/origins/example3.com \ - -H 'accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'authorization: test_key.12345678abcdefghijklABCDEFGHIJKL' \ - -d '{ - "priority": [1, 20, 255] -}' -``` - -You have now successfully configured the waiting room to support priorities. To prioritize the traffic, you must pass the priority to the `handleVwrsRequest()` and `handleVwrsResponse()` functions. Here's a template demonstrating how to include a priority with the request in the `handleVwrsRequest()` call: - -```js -export async function onClientRequest(request: EW.IngressClientRequest) { - await client.handleVwrsRequest(request, { priority: 1 }); -} -``` - -This template sets the priority of this request to 1. - -Several methods are available to retrieve the actual priority, such as query parameters, headers, or cookies. The precise method is entirely up to the specific implementation needs of the application. - -### Query Parameter Example - -```bash -GET /checkout?waiting-room-priority=20 -``` - -The example adds the request to the waiting room with a priority of 20. - -```js -export async function onClientRequest(request: EW.IngressClientRequest) { - const queryParams = new URLSearchParams(request.query); - const reqPriority = parseInt(queryParams.get("waiting-room-priority"), 10); - await client.handleVwrsRequest(request, { priority: reqPriority }); -} -``` - -### HTTP Header Example - -```bash -GET /checkout -x-waiting-room-priority: 20 -``` - -The example adds the request to the waiting room with a priority of 20. - -```js -export async function onClientRequest(request: EW.IngressClientRequest) { - const reqPriorityStr = request.getHeader("x-waiting-room-priority")[0]; - Const reqPriority = parseInt(reqPriorityStr, 10); - await client.handleVwrsRequest(request, {priority: reqPriority}); -} -``` - -### HTTP Cookie Example - -``` -GET /checkout -Cookie: waiting-room-priority=20 -``` - -The example adds the request to the waiting room with a priority of 20. - -``` -export async function onClientRequest(request: EW.IngressClientRequest) { - const cookies = new Cookies(request.getHeader("Cookie")); - const reqPriority = parseInt(cookies.get("waiting-room-priority"), 10); - await client.handleVwrsRequest(request, {priority: reqPriority}); -} -``` - -## EdgeWorker Example - -An example of `main.js` in an EdgeWorker bundle: - -```js -import { logger } from "log"; -import VirtualWaitingRoom from "./library/virtualWaitingRoom.js"; - -const virtualWaitingRoomConfiguration = new VirtualWaitingRoom({ - apiKey: "YourAPIKey", - digestKey: "YourVwrsDigestKey", - encryptionKey: "YourVwrsEncryptionKey", - vwrsMetricHost: "api-demo-vwr-metrics.paas.macrometa.io", - vwrsHost: "api-demo-vwr.paas.macrometa.io", - isFailOpen: "true", - originAccessMode: "ORIGIN_USAGE_TIME", - statusConfigLimits: { - avgWaitingTime: true, - qDepth: true, - Position: true, - }, -}); - -export async function onClientRequest(request) { - const reqOptions = { - waitingRoomPath: "/1473985/doc.html", - debugMode: true, - extraFingerprint: [request.getVariable("PMUSER_TFDH")], - }; - - const result = await virtualWaitingRoomConfiguration.handleVwrsRequest( - request, - reqOptions - ); - if (result.waitingRoom) { - // Request sent to waiting room - } -} - -export async function onClientResponse(request, response) { - const reqOptions = { - debugMode: true, - extraFingerprint: [request.getVariable("PMUSER_TFDH")], - }; - - const result = await virtualWaitingRoomConfiguration.handleVwrsResponse( - request, - response, - reqOptions - ); - if (result.waitingRoom) { - // Request sent to waiting room - } -} -``` diff --git a/docs/photoniq/vwrs/configure-vwrs-waitingroom-page.md b/docs/photoniq/vwrs/configure-vwrs-waitingroom-page.md deleted file mode 100644 index 310a7c3993..0000000000 --- a/docs/photoniq/vwrs/configure-vwrs-waitingroom-page.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -sidebar_position: 30 -title: Configure the VWRs Waiting Room Page ---- - -The VWRs waiting room page is an [HTML page](waitingroom) that users see when they are directed to the waiting room. Here is an example of such a page: - -![Waiting Room Page](/img/photoniq/vwr/vwr-activity.jpg) - -This HTML page is entirely customizable. The class attributes _queue-position_, _queue-depth_, and _avg-wait-time_ show the position of the visitors in the queue. The waiting room page is hosted on the Akamai NetStorage and is configured using the `waitingRoomPath` option in the VWRs EdgeWorker `handleVwrsRequest()` function. - -## Waiting Room Page Configuration - -The waiting room path must be configured as [a Conditional Origin](https://techdocs.akamai.com/property-mgr/docs/conditional-origins) in Akamai's property manager. This allows the waiting room HTML page to be served from the Akamai NetStorage. Configure the conditional origin with the following settings: - -- Origin ID must be set to `waitingroom`. -- Set the following settings in the behaviours section: - - Origin Server: - - - Set the Origin type to Netstorage. - - Set the NetStorage Account to the appropriate account. - - Caching: - - - Caching option: cache - - Force revalidation of stale objecs: Alwayss revalidate the orign - - Maxage: 10 minutes - -![Waiting Room Page](/img/photoniq/vwr/akamai-cond-origin.png) diff --git a/docs/photoniq/vwrs/get-started-vwrs/get-started-vwrs-mobile.md b/docs/photoniq/vwrs/get-started-vwrs/get-started-vwrs-mobile.md deleted file mode 100644 index 44fa9a2315..0000000000 --- a/docs/photoniq/vwrs/get-started-vwrs/get-started-vwrs-mobile.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -sidebar_position: 20 -title: Get Started with VWRs and Mobile Apps ---- - -This guide details how to integrate Macrometa PhotonIQ Virtual Waiting Rooms (VWRs) with your mobile applications. Unlike web-based apps, mobile apps are developed for specific platforms using platform-specific UI frameworks. Mobile apps require direct API interactions to manage user experiences effectively during high traffic periods. - -## Before You Begin - -Ensure you have completed the following prerequisites before starting the integration process: - -- **Coordinate with Macrometa Personnel:** Secure the necessary credentials and access rights by engaging with Macrometa personnel. -- **Plan Your Waiting Room:** Identify the appropriate [queue type](../queue-types.md) for your application, determine which endpoints will incorporate the waiting room, and decide on the priority handling mechanisms. -- **Collect Information:** Gather essential information, including API endpoints and expected traffic metrics, to facilitate a smooth setup. - -## Integration Overview - -Integrate VWRs with your mobile applications by following these steps: - -1. **API Key Creation:** Start by creating an API key to access the VWRs system, as this key is essential for all API interactions. For instructions on creating an API key, refer to [Create an API Key](https://www.macrometa.com/docs/apiVwrs#/operations/createAPIKey). - -2. **Create and Configure a Domain:** Create a domain that hosts your waiting room. This step allows you to fine-tune how the waiting room operates and integrates with your site. For comprehensive guidance on domain configuration, refer to [Configure a Domain](../configure-domain.md). - -3. **API Usage for Queue Management:** Use the VWRs API to manage the user's position in the waiting room. This involves making periodic API calls to check the queue status and manage the user experience accordingly. - - - [Get initial position in waiting room](https://www.macrometa.com/docs/apiVwrs#/paths/api-vwr-v1-position-domain_key/get) - - [Get current position in waiting room](https://www.macrometa.com/docs/apiVwrs#/paths/api-vwr-v1-position-domain_key---request_id/get) - -## Pseudo-Code Example - -Here is a pseudo-code example illustrating how a mobile app interacts with the VWR API to manage a user's waiting experience: - -```javascript -// Initial request specifying the waiting room. -let waitingRoom = "shopping"; -let result = GET("/api/vwr/v1/position/" + waitingRoom); - -// Loop while the user is still in the waiting room. -while (result.position > 0) { - // Notify the user of their current position and expected wait time. - notifyUser(result.position, result.waiting_time); - - // Wait for the specified refresh interval before checking the position again. - sleep(result.refresh_interval); - - // Re-check the user's position using the visitor_id received from the initial call. - result = GET("/api/vwr/v1/position/" + waiting_room + "/" + result.visitor_id); -} - -// Proceed with accessing the protected resource once the user is out of the waiting room. -accessResource(); -``` - -## Next Steps - -Once your virtual waiting room is operational, consider monitoring and managing its performance to ensure optimal functionality: - -- **Metrics and Analytics:** Regularly check the VWRs metrics to assess the performance and effectiveness of your waiting room. For more information on accessing VWRs metrics, refer to [VWRs Metrics](../vwrs-metrics.md). -- **Review Usage Patterns:** Analyze usage data to optimize settings and improve user experiences. Access hourly, daily, or monthly usage statistics through the following links: - - [Hourly Usage](https://www.macrometa.com/docs/apiVwrs#/operations/getHourlyUsage) - - [Daily Usage](https://www.macrometa.com/docs/apiVwrs#/operations/getDailyUsage) - - [Monthly Usage](https://www.macrometa.com/docs/apiVwrs#/operations/getMonthlyUsage) diff --git a/docs/photoniq/vwrs/get-started-vwrs/get-started-vwrs-web.md b/docs/photoniq/vwrs/get-started-vwrs/get-started-vwrs-web.md deleted file mode 100644 index 0f1fe75ea2..0000000000 --- a/docs/photoniq/vwrs/get-started-vwrs/get-started-vwrs-web.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_position: 10 -title: Get Started with VWRs and Web Apps ---- - -This page explains how to get started with Macrometa PhotonIQ Virtual Waiting Rooms (VWRs) with your web applications. Web apps typically use HTML, CSS, and JavaScript and operate within web browsers. This guide explains the steps to connect your web app to VWRs, enhancing your ability to manage high traffic efficiently and maintain a seamless user experience. - -## Before You Begin - -Before you begin the setup process, ensure you have completed the following prerequisites: - -- **Coordinate with Macrometa Personnel:** Engage with Macrometa personnel to obtain necessary credentials and access rights. -- **Plan Your Waiting Room:** Determine the appropriate [queue type](../queue-types.md) for your needs, decide which URLs will incorporate the waiting room, and consider whether priority handling is necessary. -- **Collect Information:** Gather all required information, such as domain details and traffic expectations, to streamline the setup process. - -## Set Up the Waiting Room - -Follow these steps to establish your virtual waiting room: - -1. **Create an API Key:** Begin by creating an API key which will grant you access to the VWRs system. This key is essential for all subsequent operations. For instructions on creating an API key, refer to [Create an API Key](https://www.macrometa.com/docs/apiVwrs#/operations/createAPIKey). - -2. **Configure a VWRs EdgeWorker:** Set up a VWRs EdgeWorker to manage the waiting room functionality on the Akamai side. This configuration is crucial for handling incoming traffic and directing it appropriately. For detailed information on this process, refer to [Configure a VWRs EdgeWorker](../configure-vwrs-edgeworker.md). - -3. **Create and Configure a Domain:** Create a domain that hosts your waiting room. This step allows you to fine-tune how the waiting room operates and integrates with your site. For comprehensive guidance on domain configuration, refer to [Configure a Domain](../configure-domain.md). - -## Next Steps - -Once your virtual waiting room is operational, consider monitoring and managing its performance to ensure optimal functionality: - -- **Metrics and Analytics:** Regularly check the VWRs metrics to assess the performance and effectiveness of your waiting room. For more information on accessing VWRs metrics, refer to [VWRs Metrics](../vwrs-metrics.md). -- **Review Usage Patterns:** Analyze usage data to optimize settings and improve user experiences. Access hourly, daily, or monthly usage statistics through the following links: - - [Hourly Usage](https://www.macrometa.com/docs/apiVwrs#/operations/getHourlyUsage) - - [Daily Usage](https://www.macrometa.com/docs/apiVwrs#/operations/getDailyUsage) - - [Monthly Usage](https://www.macrometa.com/docs/apiVwrs#/operations/getMonthlyUsage) diff --git a/docs/photoniq/vwrs/get-started-vwrs/index.md b/docs/photoniq/vwrs/get-started-vwrs/index.md deleted file mode 100644 index 9ec40aa1e1..0000000000 --- a/docs/photoniq/vwrs/get-started-vwrs/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -sidebar_position: 10 -title: Get Started with VWRs ---- - -Macrometa PhotonIQ Virtual Waiting Rooms (VWRs) are essential tools for managing high traffic volumes on websites and applications (apps), ensuring server stability and enhancing user experiences during peak times. By implementing VWRs, you can prevent server overload and potential downtime, which is crucial for maintaining service availability and user satisfaction. - -## App Integration Types - -Different types of applications require distinct approaches to integrate with Virtual Waiting Rooms (VWRs). Depending on the application's platform and user interaction model, the integration process can vary significantly. The paragraphs below explain how both web and mobile applications can effectively use VWRs to manage traffic and enhance user experiences. - -### Web Apps - -Web apps, also called non-native apps or browser-based apps, typically web-based, use standard web technologies such as HTML, CSS, and JavaScript. These applications run within web browsers and are the most common type of applications integrated with VWRs. The integration process for web apps is streamlined through web-based configurations, making it straightforward to implement effective traffic management solutions. - -For more information about integrating VWRs with web apps, refer to [Get Started with VWRs in Web Apps](get-started-vwrs-web.md). - -### Mobile Apps - -Mobile apps, also called native apps or system-specific apps, are developed for specific platforms using platform-specific programming languages. Unlike web apps, mobile applications require direct API interactions to integrate with VWRs. In these scenarios, the application takes on a greater role in managing the user experience during high-traffic periods, including handling the display of waiting times and managing user expectations. - -For more information about integrating VWRs with native apps, refer to [Get Started with VWRs in Mobile Apps](get-started-vwrs-mobile.md). diff --git a/docs/photoniq/vwrs/how-vwrs-works.md b/docs/photoniq/vwrs/how-vwrs-works.md deleted file mode 100644 index 1fd86c1a48..0000000000 --- a/docs/photoniq/vwrs/how-vwrs-works.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -sidebar_position: 5 -title: How VWRs Works ---- - -Macrometa PhotonIQ Virtual Waiting Rooms (VWRs) are an advanced prioritization service that manages visitors entering a site. VWRs serves as a protective layer for your origin server, effectively managing high traffic volumes to prevent server overload. - -## Solution Overview - -The waiting room solution includes essential aspects: - -- **Origin Service**: The website for which you want to set up a virtual waiting room. -- **Origin Metrics Service**: Allows you to retrieve information about a specific domain. -- **Waiting Room Page (Domain)**: The endpoint (URL) with the waiting room attached. - -![VWR Solution Architecture](/img/photoniq/vwr/vwr-solution-architecture.png) - -## How It Works - -The VWRs workflow ensures that users are directed to the appropriate origin service while ensuring fairness in the queue and providing metrics and alerts to the administrator. - -1. Akamai EdgeWorkers check the virtual waiting room service to see if a waiting room is enabled for an origin service. -2. If there is no waiting room, then the EdgeWorker sends the request directly to the origin service. If a waiting room is enabled, then the EdgeWorker sends the request to the waiting room service. -3. The waiting room service adds the request to the waiting room associated with the domain. -4. When the user accesses the waiting room page, the page polls the virtual waiting room service for the latest waiting time and waiting room depth. -5. The waiting room page displays the waiting time and waiting room depth to the user. -6. When the waiting time is near zero, or the user is at the front of the queue, the waiting room page forwards the user to the origin service. -7. When the request is released, the waiting room service removes a request from the queue. -8. If a duplicate request is detected, then the waiting room service checks to see if the user has an active session. - 1. If it does, then the waiting room service returns the user's position in the queue. - 2. If it does not, then the waiting room service creates a new session and adds the request to the appropriate queue. -9. The waiting room service periodically checks the sessions to remove requests for expired sessions from the queues. -10. The waiting room service calculates the waiting time and queue depth every second and updates the telemetry for the origins and domains. -11. The waiting room service collects the metrics for each domain. -12. The administrator can turn customer domains on or off through Configuration APIs. -13. Requests are served from the queue for the users, based on the join time. You can configure the queue to be FIFO, random, or lottery. diff --git a/docs/photoniq/vwrs/index.md b/docs/photoniq/vwrs/index.md index a7ee9b4b51..046553e87e 100644 --- a/docs/photoniq/vwrs/index.md +++ b/docs/photoniq/vwrs/index.md @@ -3,46 +3,44 @@ sidebar_position: 1 title: Virtual Waiting Rooms (VWRs) --- -PhotonIQ Virtual Waiting Rooms (VWRs) are designed to control and manage website traffic, especially during periods of high visitor volume. These VWRs are fully programmable, allowing customization based on various parameters such as origin load, visitor thresholds, regional traffic, and behavior analysis. Key functionalities include advanced routing capabilities, which enable VWRs to identify returning customers, divert suspected bots, and serve cached content to SEO crawlers, thereby ensuring the stability of the origin server. +PhotonIQ Virtual Waiting Rooms (VWRs) are designed to control and manage website traffic, especially during peak seasons like the holidays with high visitor traffic volume. These VWRs are fully programmable, allowing customization based on parameters like origin load, visitor thresholds, regional traffic, and behavior analysis. -In operational scenarios, VWRs help maintain website functionality during traffic surges, effectively preventing server overloads and potential site downtime. The service offers features like priority queuing and real-time updates to users, aimed at enhancing the user experience by reducing waiting time. Designed for ease of implementation and maintenance, VWRs provide a solution for automated queue management, making them suitable for high-traffic websites in need of efficient traffic handling and visitor management. +Some primary functionalities present include: +- **Advanced routing capabilities**: This enables VWRs to identify returning customers, divert suspected bots, and serve cached content to SEO crawlers, thereby ensuring the stability and continuous uptime of the origin server. +- **Priority Queuing**: VWRs reduce user frustrations by providing real-time updates to users in the queue, improving user experience. Furthermore, it offers automated queue management for ease of implementation and maintenance, making it suitable for high-traffic websites needing efficient traffic handling and visitor management. -### How It Works - -When traffic is high, VWRs makes a new page separate from your origin to organize visitors. This keeps your origin from being overwhelmed. What customers see is their place in queue along with how much longer they have to wait. They keep their line even if they accidentally navigate away from the site or close the tab. - -For a more detailed explanation, refer to [How VWRs Works](how-vwrs-works.md). +Virtual waiting rooms are vital in operational scenarios, helping to maintain website functionality during traffic surges, thus effectively preventing server overloads and potential site downtime. ## Benefits of Virtual Waiting Rooms -VWRs serves as a dynamic buffer for your origin server, adeptly handling elevated traffic volumes. This capability not only prevents server overload but also maintains a seamless user experience. Key benefits include: +The VWRs act as a dynamic buffer for your origin server, efficiently handling elevated traffic volumes. This capability prevents server overload and maintains a seamless user experience. Key benefits include: ### Server Protection - **Traffic Management:** VWRs effectively manage sudden spikes in legitimate traffic, shielding your origin server from potential overload. This feature ensures continuous operation and service availability, even during unexpected traffic surges. Your origin remains surge-protected, safeguarding against infrastructure overprovisioning and autoscaling errors. -- **Resource Optimization:** By evenly distributing incoming requests, VWRs optimize the use of server resources. This prevents any single component from becoming a bottleneck, maintaining system performance during high-traffic periods and reducing the need for immediate scaling, such as in the case of EC2. +- **Resource Optimization:** By evenly distributing incoming requests, VWRs optimize the use of server resources. This distribution prevents any single component from becoming a bottleneck, maintaining system performance during high-traffic periods and reducing the need for immediate scaling, such as in the case of EC2. ### Enhanced User Experience -- **Reliability:** VWRs keep your application consistently online, reducing the likelihood of visitors encountering error pages. This reliability ensures a consistent visitor experience, which is crucial for preventing future brand risks and protecting your reputation. -- **Smooth Waiting Room Experience:** The VWR system offers a controlled, informed waiting experience for users, with real-time queue time updates. This approach minimizes frustration, avoiding redirects and refreshes, and keeps users engaged while they wait for access to your application. +- **Reliability:** VWRs keep your application consistently online, reducing the likelihood of visitors encountering error pages. This reliability ensures a consistent visitor experience, essential for preventing future downtimes and protecting your brand reputation. +- **Smooth Waiting Room Experience:** The VWR system offers a controlled, informed waiting experience with real-time queue time updates for users. This approach minimizes frustration, avoids redirects and refreshes, and keeps users engaged while waiting to access your application. - **Specialized Waiting Journeys:** Tailor waiting experiences based on user personas, providing instant value and a more personalized approach that resonates with different visitor segments. ### Service Tiers - **Behavioral Insights:** Offering various service tiers allows for a deeper understanding of user behavior. These insights can be instrumental in optimizing service delivery and tailoring user experiences to specific segments. -- **Customization Options:** Different tiers can provide customized experiences or priorities, enabling you to cater to diverse user needs and preferences. This enhances overall satisfaction and contributes to revenue and opportunity protection. +- **Customization Options:** Different tiers can provide customized experiences or priorities, enabling you to cater to diverse user needs and preferences. This tiering system enhances overall satisfaction and contributes to revenue and opportunity protection. -By implementing these measures, VWRs not only safeguard the technical infrastructure but also elevate the user experience, making them a vital component in managing web applications effectively. +By implementing these measures, VWRs safeguard the technical infrastructure while elevating the user experience, making them a vital component in managing web applications effectively. ## Features -Key capabilities of VWRs include: +Implementing VWRs into your website equips it with the following features: ### Dynamic Wait Time Updates -- **Real-Time Predictions:** Offers continually updated forecasts for wait times, enhancing user anticipation management. -- **Customizable Display:** Showcases queue data, including position and queue size, on the waiting room page with full customization options. +- **Real-Time Predictions:** VWRs offers continually updated forecasts for wait times, enhancing user anticipation management for e-commerce situations like discount and flash sales. +- **Customizable Display:** Showcases queue data, including position and queue size, on the customizable waiting room page. ### Queue Activation Control @@ -61,10 +59,10 @@ Key capabilities of VWRs include: ### Enhanced Service Tiers -- **Priority Queueing:** Allows for the establishment of priority queues, offering different levels of service to various user groups. +- **Priority Queueing:** Allows priority queues, offering different levels of service to various user groups. - **Service Optimization:** Tailors user experiences based on service tiers, enhancing overall satisfaction and efficiency. ### Access Management Post-Queue - **Regulated Site Access:** Manages post-queue access to the site, depending on user engagement and duration of visit. -- **Time-Based Access Control:** Sets limits for uninterrupted access post-queue and re-queueing protocols after a period of inactivity, balancing server load and user access. +- **Time-Based Access Control:** Set limits for uninterrupted access post-queue and re-queueing protocols after inactivity, balancing server load and user access. diff --git a/docs/photoniq/vwrs/queue-types.md b/docs/photoniq/vwrs/queue-types.md deleted file mode 100644 index e2eb78aede..0000000000 --- a/docs/photoniq/vwrs/queue-types.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_position: 25 -title: VWRs Queue Types ---- - -This page describes the different types of queues supported by Virtual Waiting Rooms. - -## FIFO - -The system operates the FIFO (first in, first out) queue on a "first come, first served" basis. As new requests are added to the queue, they push older requests closer to the front. When the system removes a request from the front of the queue, all subsequent elements move up one position. - -## Random - -In the random queuing approach, requests are chosen from the queue indiscriminately, without preference or priority. Each request in the queue possesses an equal likelihood of being selected for processing. This method is beneficial when prioritizing requests based on their arrival time or other criteria. Introducing a random element can disperse the processing load. - -## Lottery - -The lottery queuing approach uses assigned priorities and is an advanced method of selecting requests from a queue. This method gives each request a priority or weight, representing its probability of being selected for processing. When removing a request, the system conducts a "lottery" to choose the winning request based on its assigned priority. This approach enables you to prioritize specific requests by giving them a higher priority, increasing their likelihood of being selected for processing. diff --git a/docs/photoniq/vwrs/vwrs-best-practices.md b/docs/photoniq/vwrs/vwrs-best-practices.md deleted file mode 100644 index 73f64e47b7..0000000000 --- a/docs/photoniq/vwrs/vwrs-best-practices.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -sidebar_position: 110 -title: VWRs Best Practices ---- - -This page provides information on best practices for using Macrometa PhotonIQ Virtual Waiting Rooms (VWRs). - -## Refresh Interval - -In mobile applications, consider the impact on mobile device battery life and data usage when setting this interval. Frequent updates increase both consumption metrics. - -## UI Responsiveness - -In mobile applications, avoid blocking the UI while updating the waiting room status. Information should be displayed efficiently, ensuring the app remains responsive. Also, while REST API calls are generally quick, avoid UI freezes during these operations. Take advantage of the platform's asynchronous network calls. diff --git a/static/img/photoniq/event-delivery/EDS-ss-showing-connected-with-data.png b/static/img/photoniq/event-delivery/EDS-ss-showing-connected-with-data.png new file mode 100644 index 0000000000..55c2a612bf Binary files /dev/null and b/static/img/photoniq/event-delivery/EDS-ss-showing-connected-with-data.png differ diff --git a/static/img/photoniq/event-delivery/EDS-ss-showing-new-and-updated-values.png b/static/img/photoniq/event-delivery/EDS-ss-showing-new-and-updated-values.png new file mode 100644 index 0000000000..8f798020a7 Binary files /dev/null and b/static/img/photoniq/event-delivery/EDS-ss-showing-new-and-updated-values.png differ diff --git a/static/img/photoniq/p3/404-identifier.png b/static/img/photoniq/p3/404-identifier.png new file mode 100644 index 0000000000..c7f18eeff3 Binary files /dev/null and b/static/img/photoniq/p3/404-identifier.png differ diff --git a/static/img/photoniq/prerendering/accept-language.png b/static/img/photoniq/prerendering/accept-language.png new file mode 100644 index 0000000000..771ced4cb1 Binary files /dev/null and b/static/img/photoniq/prerendering/accept-language.png differ diff --git a/static/img/photoniq/prerendering/cache-manager.png b/static/img/photoniq/prerendering/cache-manager.png new file mode 100644 index 0000000000..aefba7efa5 Binary files /dev/null and b/static/img/photoniq/prerendering/cache-manager.png differ diff --git a/static/img/photoniq/prerendering/hover-policy.png b/static/img/photoniq/prerendering/hover-policy.png new file mode 100644 index 0000000000..46191eff8c Binary files /dev/null and b/static/img/photoniq/prerendering/hover-policy.png differ diff --git a/static/img/photoniq/prerendering/prerendering-metrics.png b/static/img/photoniq/prerendering/prerendering-metrics.png new file mode 100644 index 0000000000..12d7502ddb Binary files /dev/null and b/static/img/photoniq/prerendering/prerendering-metrics.png differ diff --git a/static/img/photoniq/prerendering/set-up-origin.png b/static/img/photoniq/prerendering/set-up-origin.png new file mode 100644 index 0000000000..1b1eec8554 Binary files /dev/null and b/static/img/photoniq/prerendering/set-up-origin.png differ diff --git a/static/img/prerendering/prerendering-dashboard.png b/static/img/prerendering/prerendering-dashboard.png new file mode 100644 index 0000000000..2ec57e393c Binary files /dev/null and b/static/img/prerendering/prerendering-dashboard.png differ diff --git a/static/openapi/eds-spec.json b/static/openapi/eds-spec.json index 56334f56e8..3ce91a1c1b 100644 --- a/static/openapi/eds-spec.json +++ b/static/openapi/eds-spec.json @@ -115,7 +115,7 @@ "ws://api/es/v1/subscribe": { "get": { "summary": "Subscribe to stream", - "description": "Subscribe to stream via WebSocket based on stream, type, or query parameters. Provide either `stream` or `filters` but not both or neither.\nThis API keeps the connection live and continuously receives messages from the server based on the specified `stream` or `filters`.\n\"filters\\\" is a JSON format string with different fields. For example,
\n```json\n{\n \"action\": \"add\",\n \"once\": \"TRUE | FALSE\",\n \"queries\": [\n \"select * from XXXX where n1==v1\",\n \"select * from MMMM where n2==v1 OR n3>5\",\n \"select from XXXX\"\n ]\n}\n```\nThe *path* is a dot separated fully qualified string representing a json path for an object. *once* flag (default is false) specifies if the filters needs to be applied just once.
\n*filters* can be dynamically added and removed by sending message data on web socket connection in JSON format. For example,
\n{\\\"action\\\": \\\"remove\\\", \\\"queries\\\": [ \\\"select * from XXXX where n1=v1\\\"]}\n\nOn sucessfull subscription, the websocket connection is created and the following information is returned as part of the first response message.
\n- `x-photoniq-es`: Epoch time header. This is the Unix timestamp in seconds since epoch. It provides the epoch time in seconds.\n- `x-photoniq-customerid`: Customer ID header. It includes the tenant and fabric name identifying the customer.\n\n*Note*: The stream name and the type of stream can be fetched using GDN APIs or the GDN UI.
\n**This API should not be tried from this UI**.\n", + "description": "Subscribe to stream via WebSocket based on stream, type, or query parameters. Provide either `stream` or `filters` but not both or neither.\nThis API keeps the connection live and continuously receives messages from the server based on the specified `stream` or `filters`.\n\"filters\\\" is a JSON format string with different fields. For example,
\n```json\n{\n \"action\": \"add\",\n \"once\": \"TRUE | FALSE\",\n \"queries\": [\n \"select * from XXXX where n1==v1\",\n \"select * from MMMM where n2==v1 OR n3>5\",\n \"select from XXXX\"\n ]\n}\n```\nThe *path* is a dot separated fully qualified string representing a json path for an object. *once* flag (default is false) specifies if the filters needs to be applied just once.
\nUse *filters* to dynamically add and remove message data on the Websocket connection in JSON format. For example,
\n{\\\"action\\\": \\\"remove\\\", \\\"queries\\\": [ \\\"select * from XXXX where n1=v1\\\"]}\n\nA successful subscription establishes the websocket connection and returns the following information as part of the first response message.
\n- `x-photoniq-es`: Epoch time header. This is the Unix timestamp in seconds since epoch. It provides the epoch time in seconds.\n- `x-photoniq-customerid`: Customer ID header. It includes the tenant and fabric name identifying the customer.\n\n*Note*: The stream name and the type of stream can be fetched using GDN APIs or the GDN UI.
\n**Currently, because subscriptions occurs through Websockets and curl currently offers no support for Websockets, this API should not be tried from this UI but from a terminal using wscat - a module that supports Websocket connections**. \n", "tags": [ "Manage Subscriptions" ], @@ -312,7 +312,7 @@ "properties": { "status": { "type": "string", - "description": "The health status, either \"healthy\" or \"unhealthy\"." + "description": "The health status as \"up\"." } } }