PHP SDK: Browser: opening a page

For simply retrieving HTML after JavaScript runs, the site's browser mode and the standard HTTP client are enough. Use this object when a script needs to click buttons, enter text, or scroll.

Complete SDK reference

Methods

• open()

open

open(string $url, array $capture = [], array $captchaHints = [], bool $autoCaptcha = true): BrowserPage

Open a page in the managed browser.

$page = $ctx->browser()->open($ctx->param('catalog_url'));
try { $html = $page->waitFor('.product-card')->content(); }
finally { $page->close(); }

Result and notes. Returns a BrowserPage. At most two pages can be open. Completing navigation does not guarantee that the data you need has appeared: use waitFor().

Page network responses

The second argument starts capturing before navigation. This matters when the page requests JSON immediately after opening. Matching XHR and fetch responses are captured by full URL patterns. * matches any characters, including / and query parameters. All other characters, including ?, are literal. Example: */api/products*.

This example is illustrative: an API returns 200 products while the interface shows only 20. Replace the URL pattern and fields with those of your site. The page makes the request with its own cookies and headers; no second HTTP request is sent.

<?php
function run(\Sdk\Context $ctx): void
{
    $url = (string) $ctx->param('catalog_url');
    $page = $ctx->browser()->open($url, ['*/api/products*']);
    try {
        $response = $page->waitForResponse('*/api/products*', 15000);
        if ($response === null) {
            $ctx->abort('The page did not receive an API response within 15 seconds');
        }
        if ($response['error'] !== null || $response['truncated']) {
            $ctx->abort('Response body unavailable: ' . ($response['error'] ?? 'truncated'));
        }
        if ($response['status'] !== 200) {
            $ctx->abort('API returned HTTP ' . $response['status']);
        }
        $data = $ctx->json($response['body']);
        $items = $data['items'] ?? [];
        foreach ($items as $item) {
            $ctx->emit(['name' => $item['name'], 'price' => $item['price']], (string) $item['id']);
        }
        $ctx->log('Products read from the browser response', ['count' => count($items)]);
    } finally {
        $page->close();
    }
}

If the API is paginated too, one response does not contain the entire catalog. Capture responses before clicking the next page and process each response. See BrowserPage methods.

Capture observes responses. It does not alter requests or replace site data. Arbitrary JavaScript handlers cannot run in the browser. The usual network address protections, site proxy, and browser processing limits apply.

Automatic CAPTCHA handling

autoCaptcha is optional and defaults to true. Pass false to disable automatic solving. With automatic mode disabled, the request does not start paid CAPTCHA tasks. Platform and site settings, supported challenge types and quotas still apply. The choice applies to the entire browser session, including subsequent actions and content reads.

$page = $ctx->browser()->open($url, autoCaptcha: false);

CAPTCHA on a self-hosted agent

Automatic mode and opt-out also work on your agent. A browser, connectivity to Akmelo and an eligible plan are required. No additional CAPTCHA keys need to be configured. Checks and costs belong to the agent's workspace; local execution does not make CAPTCHA handling free.

Yandex SmartCaptcha practice

The official demo allows a complete form check without an external account. CAPTCHA handling runs automatically; the script fills in a sample name and submits the form. Use only test values.

$page = $ctx->browser()->open('https://smartcaptcha.yandexcloud.net/demo', [], ['success_selector' => '.greeting']);
try {
    $page->type('#name', 'Training example');
    $page->click('#smartcaptcha-demo-submit');
    $page->waitFor('.greeting', 15000);
    $ctx->log($ctx->dom($page->content())->text('.greeting') ?? '');
} finally { $page->close(); }

A filled smart-token means the form is ready to submit. Only the server greeting with the submitted name confirms success. The CAPTCHA title and the new empty widget next to the greeting do not trigger another payment during result reading. A further visual challenge is processed in the same session up to the run limit; cancellation and deadlines stop the chain. An unsupported challenge or a rejected answer remains an error. The same SDK methods and hints work on a connected agent.

CAPTCHA usage reference

Complete CAPTCHA SDK and REST reference covers all hint fields, automatic defaults, explicit calls, session opt-out, result verification, agents, limits and failures. User guide and current prices explain setup and billing.

Object selection uses kind: "yandex_image"; automatic detection normally needs no hints. image_selector identifies only the task image, instructions_selector the selection order, and success_selector a result that appears after success. No target-domain list is needed. Unsupported variants fail instead of returning fabricated data. Do not repeatedly retry the same rejected task.

Object selection with explicit selectors

Replace these example selectors with elements from your source. Both image selectors must identify the challenge images, not the whole page. Use this only when automatic discovery is insufficient.

$page = $ctx->browser()->open($url, [], [
    'kind' => 'yandex_image',
    'image_selector' => '.challenge-image',
    'instructions_selector' => '.challenge-order',
    'submit_selector' => '.challenge-submit',
    'success_selector' => '.result',
]);
try {
    $page->waitFor('.result', 15000);
} finally { $page->close(); }