Interacting with a Page

Overview

This recipe demonstrates how to use Airtop to automate human interactions with a browser and extract stock performance data. It also makes use of Airtop’s page query API to fetch and process data from the web page.

The instructions below will guide you through creating a script that:

• Connects to Airtop
• Initializes a browser session and window
• Navigates to a stock performance page using click and type interactions
• Extracts data using the page query API
• Displays the data in a formatted manner

Demo

A live demo of this recipe is available here. You can sign up to create an API key for free and try it out yourself!

Prerequisites

To get started, ensure you have:

• Node.js installed on your system.
• PNPM package manager installed. See here for installation steps.
• A Node Version Manager (NVM preferably).
• An Airtop API key. You can get one for free.

Getting Started

1. Clone the repository

   Start by cloning the source code from GitHub:

   $
   git clone https://github.com/airtop-ai/examples-typescript
   >
   cd examples-typescript/examples/simple-interactions

2. Setup

   Follow the README instructions in the root of the cloned repository to install dependencies and build packages. Then follow the instructions in examples/simple-interactions/README.md.

Script Walkthrough

The script in simple-interactions.cli.ts performs the following tasks:

1. Initialize the Logger and Prompt for API Key

   The script starts by initializing a logger and prompting the user for their Airtop API key.

   1
   const log = getLogger();
   2
   3
   const apiKey = await input({
   4
     message: "Enter your Airtop API key:",
   5
     required: true,
   6
   });

2. Create an InteractionsService Instance

   An instance of InteractionsService is created using the provided API key, logger and a default ticker symbol. This service handles interactions with the browser.

   1
   const service = new InteractionsService({
   2
     apiKey,
   3
     log,
   4
     ticker: DEFAULT_STOCK_SYMBOL,
   5
   });

3. Initialize Session and Browser

   The script initializes a session and browser window using the initializeSessionAndBrowser method from InteractionsService.

   1
   sessionAndWindow = await service.initializeSessionAndBrowser();
   2
   const { session, windowInfo } = sessionAndWindow;

   Under the Hood:

   1
   async initializeSessionAndBrowser() {
   2
     // Create a new session
   3
     const createSessionResponse = await this.client.sessions.create({
   4
       configuration: {
   5
         timeoutMinutes: 10, // Terminate the session after 10 mins of inactivity
   6
       },
   7
     });
   8
   9
     const session = createSessionResponse.data;
   10
    
   11
     // Open a new browser window with the default URL
   12
     const windowResponse = await this.client.windows.create(session.id, {
   13
       url: INITIAL_URL,
   14
     });
   15
   16
     // Get the window information
   17
     const windowInfo = await this.client.windows.getWindowInfo(session.id, windowResponse.data.windowId);
   18
   19
     // Return session and window information, including a live view
   20
     return { session, windowInfo };
   21
   }

4. Search for Stock Performance

   The script uses the searchForStockPerformance method to search for stock performance data.

   1
   await service.searchForStockPerformance({
   2
     sessionId: session.id,
   3
     windowId: windowInfo.data.windowId,
   4
   });

   Under the Hood:

   1
   async searchForStockPerformance({ sessionId, windowId }: { sessionId: string; windowId: string }) {
   2
    // Type the ticker symbol into the search box and press enter
   3
    await this.client.windows.type(sessionId, windowId, {
   4
      elementDescription: "The search box",
   5
      text: this.ticker,
   6
      pressEnterKey: true,
   7
    });
   8
   }

5. Click on Stock Performance Chart

   The script simulates a click on the stock performance chart using the clickOnStockPerformanceChart method.

   1
   await service.clickOnStockPerformanceChart({
   2
     sessionId: session.id,
   3
     windowId: windowInfo.data.windowId,
   4
   });

   Under the Hood:

   1
   async clickOnStockPerformanceChart({ sessionId, windowId }: { sessionId: string; windowId: string }) {
   2
     // Identify the chart element using natural language and simulate a click
   3
     await this.client.windows.click(sessionId, windowId, {
   4
       elementDescription: "The '6M' button at the top of the chart",
   5
     });
   6
   }

6. Extract Stock Performance Data

   The script extracts stock performance data using the extractStockPerformanceData method and formats it for display.

   1
   const content = await service.extractStockPerformanceData({
   2
     sessionId: session.id,
   3
     windowId: windowInfo.data.windowId,
   4
   });
   5
   6
   const formattedJson = JSON.stringify(JSON.parse(content), null, 2);
   7
   log.info("Response:\n\n", chalk.green(formattedJson));

   Under the Hood:

   1
   async extractStockPerformanceData({ sessionId, windowId }: { sessionId: string; windowId: string }) {
   2
     // Use the pageQuery API to extract stock performance data
   3
     const modelResponse = await this.client.windows.pageQuery(sessionId, windowId, {
   4
       prompt: STOCK_PERFORMANCE_PROMPT(this.ticker),
   5
       configuration: {
   6
         outputSchema: STOCK_PERFORMANCE_OUTPUT_SCHEMA(this.ticker),
   7
       },
   8
     });
   9
   10
     // Return the extracted data
   11
     return modelResponse.data.modelResponse;
   12
   }

7. Clean Up

   Finally, the script ensures that the session is terminated to clean up resources.

   1
   if (sessionAndWindow?.session) {
   2
     await service.terminateSession(sessionAndWindow.session.id);
   3
   }

   Under the Hood:

   1
   async terminateSession(sessionId: string) {
   2
     // Terminate the session to release resources
   3
     await this.client.sessions.terminate(sessionId);
   4
   }

Running the Script

To run the script, execute the following command in your terminal:

$
pnpm run cli

This command uses the cli script defined in the package.json file, which runs the simple-interactions.cli.ts file using tsx.

Summary

This recipe demonstrates how Airtop can be utilized to automate tasks that require browser interactions which would otherwise require manual intervention. Compounded with other Airtop APIs like the page query API, it can be used to build powerful automation workflows.