Playground

Playground is an interactive tool for writing and evaluating queries in real time. Whether you are learning from examples in the documentation or developing personalized experiences, it is a convenient way to experiment with CQL.

Did you know?

Playground is a showcase of what you can do with Croct. It's built on top of our SDK, which means you can build something like this yourself!

One of its key features is the ability to connect to your application and run queries against live sessions. This is particularly useful for exploring how different events, user profiles, and application contexts can impact the evaluation of your expressions.

Accessing Playground

You can either access Playground in an unauthenticated way via URL or in an authenticated way via API key, each with its own advantages and use cases.

The following table summarizes the differences between the two options:

Accessing via URL

This is the easiest way to access Playground — all you need to do is enter your application's URL. However, remember that it uses a sandbox environment, so you won't be able to access your application's specific data.

To access the sandbox environment, follow these steps:

1. Click the following link to open Playground:
   https://play.croct.com

2. Enter the URL of your application.

   You can use a local URL like http://localhost:3000 if you are running your application locally.

3. Click Let's play.

Accessing via API Key

For a more real-world experience, consider accessing Playground using your application's API key. This allows you to run queries against your actual data and test real-world scenarios, which is especially useful for debugging and troubleshooting.

If you do not have an API key, you can create one as follows:

1. On your workspace, click Applications in the left sidebar.

2. Click the application you want to access.

3. Click API Keys in the left sidebar.

4. Click the + New button in the right corner.

5. Enter a name for your API key and check the Authentication box.

6. Click Save.

7. Copy the API key and save it somewhere safe.

Now that you have an API key, you can access Playground as follows:

1. Click the following link to open Playground:
   https://play.croct.com

2. Click the Already have an API key? link.

3. Enter your API key.

4. Click Let's play.

You are all set! Let's now take a look at how to use the Playground.

Using Playground

Once you enter Playground, you will see an editor in the center of the screen where you will write your expressions.

To evaluate a query, simply type it in the editor and click Evaluate:

Once you run the evaluation, the result will appear below the editor. If the query is valid, you will see its result. Otherwise, you will see an error message explaining what went wrong.

Connecting to your application

If you are using Playground with your API key, you can connect to your application and run queries against your live sessions.

To connect to your application, click the button with your application's domain name in the upper-right corner of the screen. This will open a new tab with your application.

Once you return to the Playground tab, you will see that the button has turned green, along with a notification that you are connected to your application.

Let's see how this works in practice:

1. Copy the following query into your editor:

   page's title

2. Click Evaluate.

   You should see the same title as the tab you just opened, confirming that the query is running against your live session.

3. Switch to Live mode by clicking the switch next to the Evaluate button.

   A blue dot should appear in the Playground tab, indicating that the result of the query has changed.

4. Return to Playground and notice that the result now shows the title of the page you just visited.

You can now try any query and see how it behaves in real time. Check out the cheat sheet in the top right corner of the page for some examples to get you started.

Leveraging writing assistance

Playground also supports assisted query writing, which is especially useful for learning and exploring the available expressions.

As you start typing, some suggestions will appear inline. You can use Tab to apply the first suggestion or Ctrl + ↑ / ↓ to navigate between suggestions:

To see a list of suggestions, press Ctrl + Space and use the arrow keys to navigate the list and press Enter to select a suggestion:

Throughout the documentation, you will come across several examples that include placeholders, such as the one below:

no /*<subject>*/ in /*<collection>*/ satisfies /*<condition>*/

These placeholders should be replaced with real values. Click or press Tab to select a placeholder, and then type the value you want to use:

Using shortcuts

When working in Playground, you can take advantage of several keyboard shortcuts to speed up your workflow.

Here is the list of available shortcuts: