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

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 (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 (lines 67-81) and 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.

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).
• 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).

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).

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 (lines 13-25), the XiaoHongShu implementation deliberately filters for only the web_session key, whereas 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}