You can get started with a full TypeScript example here.

​
Client: Get Session Status

Method client.getSessionStatus | API Endpoint

​
Description

This method retrieves the status of a session associated with a specified account.

​
Usage

// Define the input for the getSessionStatus method
const getSessionInput = {
  account: {
    ownerId: "app_user_id", // Replace with the app user id
    domain: "app_enum",   // Replace with the app enum string
  },
};

// Call the getSessionStatus method
client.getSessionStatus(getSessionInput)
  .then((result) => {
    if ("status" in result) {
      console.log("Session status:", result.status); // Output the session status
    } else {
      console.error("Error:", result); // Handle the GetSessionError response
    }
  })
  .catch((error) => {
    console.error("An error occurred:", error.message);
  });

​
Client: Delete Session

Method client.deleteSession | API Endpoint

​
Description

This method deletes a session associated with a specified account.

​
Usage

// Define the input for the deleteSession method
const deleteSessionInput = {
  account: {
    ownerId: "app_user_id", // Replace with the app user id
    domain: "app_enum",   // Replace with the app enum string
  },
};

// Call the deleteSession method
client.deleteSession(deleteSessionInput)
  .then((result) => {
    // Handle the success response
    if ("message" in result) {
      console.log(result.message); // Output: Session removed successfully
    } else {
      console.error(result); // Handle the error response
    }
  })
  .catch((error) => {
    console.error("An error occurred:", error.message);
  });

​
Execute Runtime Script

Function executeRuntimeScript

​
Description

Executes a runtime script within a browser context.

This function runs given Playwright scripts within a specified page or browser context. The page or browser context is supported with Anon’s session cookies and proxies. It ensures the setup and cleanup of browser resources after the script execution.

​
Usage

const account = {
  // check out the list of supported integrations on docs.anon.com
  // should align with a previously connected user session
  app: "amazon",
  // this is the "sub" field of your user's JWTs
  userId: APP_USER_ID,
};

const client = new Client({
  environment: "sandbox",
  // create a server SdkClient and use its ApiKey
  // for testing, can alternately use an admin member's api key
  apiKey: API_KEY,
});

console.log(
  `Setting up browser script for ${account.app} session for app user id ${APP_USER_ID}`,
);
const { browserContext } = await setupAnonBrowserWithContext(
  client,
  account,
  { type: "local", input: { headless: false } },
);
await executeRuntimeScript({
  client,
  account,
  target: { browserContext: browserContext },
  initialUrl: "https://www.linkedin.com",
  run: async (page: Page) => {
	  console.log("navigating to messages!");
	  await page.goto("https://linkedin.com/messaging/?");
    await page.mainFrame().waitForLoadState();
  },
});

​
Setup Anon Browser With Context

Function setupAnonBrowserWithContext

​
Description

This function initializes a browser and its context, configured with proxy settings. The initialized browser context can be used to execute browser scripts. It supports managed (remote browser managed by Anon), remote (other remote url), and local launch options.

​
Usage

const { browserContext } = await setupAnonBrowserWithContext(
  client,
  account,
  { type: "local", input: { isAnonProxyEnabled: true } },  // browserLaunchOptions
);

The third parameter is an object browserLaunchOptions which takes a type key with value "local" | "remote" | "managed" and additional input parameters.

​
type Options

​
type: "local"

Allows you to self-host Playwright sessions, on your own backend servers or developer machines.

const { browserContext } = await setupAnonBrowserWithContext(
  client,
  account,
  { type: "local", input: { headless: false, isAnonProxyEnabled: true } },
);

The type for browserLaunchOptions is { type: "local"; input: LocalBrowserLaunchInput }.

input: LocalBrowserLaunchInput extends Playwright’s LaunchOptions and includes an optional proxy property:

type LocalBrowserLaunchInput = Omit<LaunchOptions, "proxy"> & {
  proxy?: LocalProxyConfig | AnonProxyConfig;
};

Where:

  • LocalProxyConfig allows you to specify your own proxy:
type LocalProxyConfig = {
  server: string;
  bypass?: string;
  username?: string;
  password?: string;
};
  • AnonProxyConfig allows you to use Anon’s proxy or disable proxying:
type AnonProxyConfig = {
  isAnonProxyEnabled?: boolean;
};

By default, if the proxy or isAnonProxyEnabled property is omitted, then no proxies will be used.

​
type: "remote"

The type for browserLaunchOptions is { type: "remote" | "self-hosted"; input: string }.

input: string is the remote url to connect to.

Allows you to host Playwright sessions on a remote provider, like Browserbase, or your own remote url.

const { browserContext } = await setupAnonBrowserWithContext(
  client,
  account,
  {
    type: "remote",
    input: `wss://connect.browserbase.com?apiKey=${process.env.BROWSERBASE_API_KEY}`,
  },
)

​
type: "managed"

The type for browserLaunchOptions is { type: "managed"; input: ProxyConfig }. ProxyConfig has the following type:

type ProxyConfig = {
  isAnonProxyEnabled?: boolean;
} | {
  server: string;
  bypass?: string;
  username?: string;
  password?: string;
};

This option allows you to configure your own proxy settings, or disable proxying.

Utilizing a managed browser runtime environment offers a user the ability to use Anon’s proxy servers, or configure their own proxy servers.

const { browser } = await setupAnonBrowserWithContext(
  client,
  account,
  { type: "managed", input: { isAnonProxyEnabled: true }, },
);

const page = browser.contexts()[0].pages()[0];

await executeRuntimeScript({
  client,
  account,
  target: { page },
  initialUrl: "www.example.com",
  run,
});

A developer can even configure their own proxy servers to the managed browser runtime environment.

const { browserContext } = await setupAnonBrowserWithContext(
  client,
  account,
  { type: "managed", input: { server: "https://your-proxy-server:8080", username: "username", password: "password" } },
);

const page = browser.contexts()[0].pages()[0];

await executeRuntimeScript({
  client,
  account,
  target: { page },
  initialUrl: "www.example.com",
  run,
});

​
Detailed Usage

Running this script will indicate your location as setupAnonBrowserWithContext proxies your requests to nearby servers.

const account = { app: "amazon", userId: APP_USER_ID };

const client = new Client({ environment: "sandbox", apiKey: API_KEY });

type LumTestResponse = {
  geo: {
    city: string;
    region: string;
    country: string;
  }
}

const getProxyGeoInformation = async (page: Page): Promise<LumTestResponse> => {
  await page.goto("https://lumtest.com/myip.json");
  const json = await page.textContent("body");
  if (json) {
    return JSON.parse(json) as LumTestResponse;
  } else {
    throw new Error("Unable to get IP");
  }
}

console.log(
  `Setting up browser script for ${account.app} session for app user id ${APP_USER_ID}`,
);

const { browserContext } = await setupAnonBrowserWithContext(
  client,
  account,
  { type: "local", input: {} },
);
const geoInfo = await executeRuntimeScript({
  client,
  account,
  target: { browserContext },
  initialUrl: "https://lumtest.com/myip.json",
  run: getProxyGeoInformation,
});

console.log(`Made a request from ${geoInfo.geo.city}, ${geoInfo.geo.region}, ${geoInfo.geo.country}`);

​
Initialize Anon Browser

Function initializeAnonBrowser

​
Description

This function is only for type: "local" browser instances.

We recommend using setupAnonBrowserWithContext for most use cases, since that function sets up both your browser and browser context.

Initializes an Anon browser instance based on the provided launch options. This function supports launching a local browser, connecting to a remote browser, or initializing a managed browser environment hosted by Anon.

​
Detailed Usage

const browser = await initializeAnonBrowser({
  type: "local",
  input: {},
});

const browserContext = await setupAnonBrowserContext(client, account, browser);
const geoInfo = await executeRuntimeScript({
  client,
  account,
  target: { browserContext },
  initialUrl: "https://lumtest.com/myip.json",
  run: getProxyGeoInformation,
});

​
Setup Anon Browser Context

Function setupAnonBrowserContext

​
Description

This function is only for type: "local" browser instances.

We recommend using setupAnonBrowserWithContext for most use cases, since that function sets up both your browser and browser context.

Sets up a browser context with optional proxy settings and additional context options. This function initializes a new browser context within the given browser instance, configured with the provided proxy settings and context options.

contextOptions is from Playwright’s BrowserContextOptions.

​
Detailed Usage

const browser = await initializeAnonBrowser({
  type: "local",
  input: {},
});

const browserContext = await setupAnonBrowserContext(client, account, browser, contextOptions);
const geoInfo = await executeRuntimeScript({
  client,
  account,
  target: { browserContext },
  initialUrl: "https://lumtest.com/myip.json",
  run: getProxyGeoInformation,
});

Was this page helpful?