# MediaCrawler Login Types Explained: QR-Code vs Phone vs Cookie Authentication

> Discover QR-code, phone, and cookie authentication in MediaCrawler. Learn how to choose the right login type for your needs and integrate seamlessly with NanmiCoder MediaCrawler.

- Repository: [程序员阿江-Relakkes/MediaCrawler](https://github.com/NanmiCoder/MediaCrawler)
- Tags: deep-dive
- Published: 2026-06-30

---

**MediaCrawler supports three mutually exclusive authentication strategies—QR-code scanning, SMS-based phone verification, and direct cookie injection—controlled by the global `config.LOGIN_TYPE` setting and implemented in platform-specific login classes.**

The open-source MediaCrawler repository (NanmiCoder/MediaCrawler) provides robust login mechanisms for Chinese social platforms including Zhihu, XiaoHongShu, and Douyin. Each login type targets different automation scenarios, ranging from interactive manual authentication to fully headless session management.

## How QR-Code Login Works

QR-code login detects dynamically generated authentication codes on platform login pages and blocks execution until a mobile device scans the code. This method requires visual access to the rendered browser window.

The implementation extracts QR images using two distinct approaches depending on the platform:

- **Canvas-based extraction**: In [`media_platform/zhihu/login.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/zhihu/login.py) (lines 81-107), `ZhiHuLogin.login_by_qrcode` uses `utils.find_qrcode_img_from_canvas` to read pixel data from HTML5 `<canvas>` elements.
- **Image-based extraction**: XiaoHongShu and Douyin implementations use `utils.find_login_qrcode` to fetch the `src` attribute of `<img>` tags, as seen in [`media_platform/xhs/login.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/xhs/login.py) (lines 67-81) and [`media_platform/douyin/login.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/douyin/login.py) (lines 24-33).

After extraction, `utils.show_qrcode` renders the base64-encoded image in the terminal. The system then polls `check_login_state` in a retry loop until the platform validates the scan and sets authentication cookies.

```python
from media_platform.zhihu.login import ZhiHuLogin

login = ZhiHuLogin(
    login_type="qrcode",
    browser_context=browser_context,
    context_page=page,
)

await login.begin()  # Displays QR and blocks until scan completes

```

## How Phone Login Works

Phone login automates SMS-based authentication by entering a phone number, triggering verification code delivery, and submitting the code programmatically. This method requires a Redis instance to receive SMS messages from external services.

The workflow varies by platform:

- **XiaoHongShu**: `XiaoHongShuLogin.login_by_mobile` fills the phone number, clicks the send button, and polls Redis for a key named `xhs_<phone>` before submitting the form (lines 99-156 in [`media_platform/xhs/login.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/xhs/login.py)).
- **Douyin**: `DouYinLogin.login_by_mobile` uses Redis key `dy_<phone>` and includes additional slider captcha handling (lines 39-70 in [`media_platform/douyin/login.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/douyin/login.py)).

```python
from media_platform.xhs.login import XiaoHongShuLogin

login = XiaoHongShuLogin(
    login_type="phone",
    browser_context=browser_context,
    context_page=page,
    login_phone="13800138000",
)

await login.begin()  # Waits for SMS in Redis key xhs_13800138000

```

## How Cookie Login Works

Cookie login bypasses UI authentication entirely by injecting pre-exported session data directly into the Playwright `BrowserContext`. This enables immediate authenticated access without waiting for QR scans or SMS delivery.

Implementation details differ across platforms:

- **Zhihu**: `ZhiHuLogin.login_by_cookies` injects all cookies from the string after parsing with `utils.convert_str_cookie_to_dict` (lines 15-25).
- **XiaoHongShu**: `XiaoHongShuLogin.login_by_cookies` specifically filters for the `web_session` cookie and ignores others (lines 13-25).
- **Douyin**: `DouYinLogin.login_by_cookies` adds all provided cookies to the context (lines 66-75).

```python
from media_platform.douyin.login import DouYinLogin

cookie_str = "sessionid=abc123; sid_guard=xyz789;"
login = DouYinLogin(
    login_type="cookie",
    browser_context=browser_context,
    context_page=page,
    cookie_str=cookie_str,
)

await login.begin()  # Immediate authentication via browser_context.add_cookies()

```

## Comparing Authentication Strategies

Each login type suits different operational requirements:

- **QR-code**: Best for fresh accounts without existing sessions. Requires the browser window to remain visible during startup but avoids SMS costs and external dependencies.
- **Phone**: Useful when QR-code entry is rate-limited or disabled. Requires a working Redis server and external SMS receiving infrastructure.
- **Cookie**: Ideal for headless batch crawling and CI/CD pipelines. Demands valid, non-expired cookies but eliminates waiting periods and UI interactions.

## Summary

- **QR-code login** extracts authentication images from either `<canvas>` or `<img>` elements and blocks execution until mobile app scan completion.
- **Phone login** automates SMS verification by polling platform-specific Redis keys (`xhs_<phone>`, `dy_<phone>`) and handles slider challenges on some platforms.
- **Cookie login** provides instant authentication via `browser_context.add_cookies()`, with platform-specific filtering (Zhihu accepts all cookies, XiaoHongShu requires only `web_session`).
- All three methods are mutually exclusive and selected via the global `config.LOGIN_TYPE` configuration value.

## Frequently Asked Questions

### Which login type works best for completely headless automation?

**Cookie login** is optimal for headless environments because it injects session data directly via `login_by_cookies` without requiring UI rendering or manual interaction, whereas QR-code requires visual confirmation and phone login needs SMS orchestration.

### Why does XiaoHongShu cookie login only use the web_session cookie while Zhihu uses all cookies?

According to the source code in [`media_platform/xhs/login.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/xhs/login.py) (lines 13-25), the XiaoHongShu implementation deliberately filters for only the `web_session` key, whereas [`media_platform/zhihu/login.py`](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/zhihu/login.py) (lines 15-25) iterates over all cookie key-value pairs from the parsed string.

### How does the phone login method receive SMS verification codes without manual entry?

The implementation polls a Redis cache using platform-specific keys formatted as `<platform>_<phone_number>` (e.g., `xhs_13800138000` or `dy_13800138000`). An external SMS forwarding service must populate this key with the received code for the automation to proceed.

### Can I switch between login methods without changing code?

Yes. Modify the `LOGIN_TYPE` setting in your configuration file to `"qrcode"`, `"phone"`, or `"cookie"`. The abstract login classes in each platform module route to the appropriate `login_by_qrcode`, `login_by_mobile`, or `login_by_cookies` method based on this global value.