راهنمای پیکربندی UA Pro

وارد و صادر کردن پیکربندی و پیکربندی از راه دور

پشتیبان‌گیری، انتقال و نوشتن دستی پیکربندی و بارگذاری آن از نشانی راه دور.

نسخه مورد استفاده: UA Pro 1.5.0

این راهنما برای UA Pro 1.5.0 است و پشتیبان‌گیری، انتقال، نوشتن دستی پیکربندی و بارگذاری آن از نشانی راه دور را توضیح می‌دهد. نسخه جدید از قالب تصویر کامل استفاده می‌کند و version فایل پیکربندی برابر 2 است.

پیش از وارد کردن، در مرورگر مقصد یک نسخه پشتیبان صادر کنید. هر بار وارد کردن، قاعده سراسری، مجموعه کامل قواعد دامنه، دو کتابخانه UA و کلید قاعده جایگزین دامنه منبع را با تصویر کامل موجود در فایل جایگزین می‌کند و موارد را جداگانه ادغام نمی‌کند. "globalRule": null به معنی پاک کردن قاعده سراسری مرورگر مقصد است.

01صادر کردن پیکربندی

  1. روی نماد UA Pro در نوار ابزار مرورگر کلیک کنید.
  2. «بیشتر» ← «وارد/صادر کردن پیکربندی» را باز کنید.
  3. روی «صادر کردن پیکربندی» کلیک کنید و فایل .json دانلودشده را ذخیره کنید.
  4. نام فایل شبیه ua-switcher-config-2026-11-16.json است. تاریخ نام فایل بر اساس UTC ساخته می‌شود و ممکن است یک روز با تاریخ محلی تفاوت داشته باشد.

فایل شامل تنظیمات ماندگار زیر است:

  • قاعده سراسری و وضعیت فعال یا متوقف بودن آن.
  • مجموعه قواعد دامنه و وضعیت فعال یا متوقف بودن هر یک.
  • دسته‌ها و موارد UA سفارشی.
  • دسته‌ها و موارد متن الحاقی.
  • کلید «قاعده جایگزین دامنه منبع».

فایل شامل موارد زیر نیست: قواعد برگه، اتصال‌های UA تصادفی که قبلاً انتخاب شده‌اند، برگه‌های باز فعلی، زبان رابط، پوسته و تنظیمات لایه شناور. پس از وارد کردن، این موارد از نسخه پشتیبان بازگردانی نمی‌شوند؛ قواعد برگه موجود در مرورگر مقصد نیز با وارد کردن پاک نمی‌شوند و ممکن است همچنان بر قواعد دامنه یا سراسری اولویت داشته باشند.

فایل صادرشده JSON متنی و خواناست. اگر UA سفارشی یا دسته‌ای اطلاعاتی دارد که نمی‌خواهید منتشر شود، نسخه پشتیبان را با دقت نگهداری کنید.

02وارد کردن از فایل محلی

  1. در مرورگر مقصد UA Pro ← «بیشتر» ← «وارد/صادر کردن پیکربندی» را باز کنید.
  2. ابتدا روی «صادر کردن پیکربندی» کلیک کنید تا پیکربندی اولیه مرورگر مقصد برای بازیابی احتمالی حفظ شود.
  3. روی «وارد کردن پیکربندی» کلیک و فایل .json را انتخاب کنید.
  4. هشدار جایگزینی و تعداد قواعد و فهرست‌ها را بخوانید؛ با «مشاهده محتوای پیکربندی» می‌توانید پیش از تأیید کل JSON را بررسی کنید. انتخاب «لغو» چیزی نمی‌نویسد. پس از تأیید منتظر پیام «پیکربندی وارد شد!» بمانید. اگر تنظیمات هنگام تأیید تغییر کند، افزونه درخواست تکرار عملیات می‌کند.
  5. قواعد سراسری و دامنه، فهرست‌های سفارشی و کلید قاعده جایگزین دامنه منبع را بررسی کنید؛ ببینید آیا قواعد برگه موجود بر آن‌ها اولویت دارند. صفحه مورد آزمایش را تازه‌سازی و سپس UA را بررسی کنید.

افزونه ابتدا فایل را بررسی می‌کند، سپس نصب قواعد را امتحان می‌کند و در پایان پیکربندی ماندگار را می‌نویسد. اگر نصب یا نوشتن شکست بخورد، برای بازگرداندن قواعدی که اکنون در مرورگر ذخیره شده‌اند تلاش می‌کند؛ اگر اعلام شد بازیابی ممکن نیست، تنظیمات واقعی را بررسی کنید. اگر همگام‌سازی مرورگر یا پنجره دیگری هم‌زمان پیکربندی را تغییر دهد، نباید این فرایند را تراکنشی میان دستگاه‌ها دانست.

03بارگذاری از نشانی راه دور

پیکربندی از راه دور از همان محتوای JSON نسخه پشتیبان محلی استفاده می‌کند. این کار بارگذاری و وارد کردن دستی و یک‌باره است، نه اشتراکی با به‌روزرسانی خودکار.

  1. ابتدا پیکربندی را برای پشتیبان‌گیری صادر کنید یا مطابق راهنمای زیر فایل JSON آماده کنید.
  2. فایل را روی سرویس HTTPS قابل دسترس از مرورگر مقصد قرار دهید و نشانی کامل بازگرداننده مستقیم محتوای JSON را بگیرید، مانند https://example.com/ua-pro/config.json. این نشانی فقط نمونه است؛ آن را با نشانی واقعی خود جایگزین کنید.
  3. در ⁨UA Pro⁩، «بیشتر» و سپس «وارد/صادر کردن پیکربندی» را باز کنید، بخش «پیکربندی از راه دور» را گسترش دهید، نشانی را بچسبانید و روی «بارگذاری» کلیک کنید.
  4. پس از موفقیت بارگذاری و بررسی قالب، افزونه پنجره تأیید و نام میزبان راه دور را نمایش می‌دهد؛ با «مشاهده محتوای پیکربندی» می‌توانید JSON کامل واقعاً دانلودشده را بررسی کنید. تأیید تنظیمات را طبق همان قواعد وارد کردن محلی به‌روزرسانی می‌کند؛ لغو چیزی وارد نمی‌کند.
  5. پس از تغییر فایل روی سرور، برای استفاده از محتوای جدید باید نشانی را دوباره وارد، بارگذاری و تأیید کنید. هنگام باز کردن دوباره پنل، نشانی خودکار حفظ نمی‌شود.

فقط پیوند مستقیم HTTPS پذیرفته می‌شود؛ HTTP، نام کاربری یا گذرواژه در نشانی و بخش fragment نشانی پذیرفته نیست و تغییر مسیر دنبال نمی‌شود. درخواست حاوی Cookie مرورگر یا اطلاعات ورود نیست، Referer ارسال نمی‌کند و حافظه نهان را دور می‌زند؛ بنابراین سرویس نیازمند Cookie ورود مناسب نیست. UA Pro قواعد UA تنظیم‌شده در این افزونه را بر این درخواست اعمال نمی‌کند، اما افزونه‌های دیگر یا تجهیزات شبکه ممکن است درخواست را تغییر دهند. نشانی می‌تواند پارامتر پرس‌وجو داشته باشد؛ از نشانی دارای توکن دسترسی مانند گذرواژه محافظت کنید. از نشانی قابل اعتماد استفاده کنید و مطمئن شوید پاسخ مستقیماً فایل JSON است، نه صفحه ورود یا صفحه HTML نمایش‌دهنده کد.

فایل محلی و پاسخ راه دور هر دو به 128 KiB محدودند؛ خواندن راه دور حداکثر 10 ثانیه زمان دارد و محتوای واقعاً خوانده‌شده شمارش می‌شود. ذخیره‌سازی همگام مرورگر سهمیه کوچک‌تری برای هر مورد دارد، پس حتی فایل زیر 128 KiB نیز ممکن است به علت بزرگی قواعد یا یک کتابخانه ذخیره نشود. در صورت خطا بررسی کنید سرور وضعیت 200 و JSON معتبر برمی‌گرداند، گواهی معتبر است، نشانی تغییر مسیر نمی‌دهد و شبکه قابل دسترس است.

04نمونه کامل JSON

نمونه زیر را می‌توان به صورت config.json با کدگذاری UTF-8 ذخیره کرد. دامنه‌ها و مقادیر UA نمونه فقط برای توضیح‌اند؛ پیش از جایگزینی از پیکربندی موجود پشتیبان بگیرید. JSON به بزرگی و کوچکی حروف حساس است؛ برای رشته‌ها از گیومه دوتایی ASCII استفاده کنید، پس از آخرین عنصر ویرگول نگذارید و در JSON توضیح ننویسید.

JSON
{
  "version": 2,
  "type": "ua-switcher-config",
  "timestamp": "2026-11-16T06:00:00.000Z",
  "data": {
    "globalRule": {
      "enabled": true,
      "mode": "builtin",
      "params": {
        "os": "Windows",
        "uaKey": "Edge 125 (Latest)"
      }
    },
    "domainRules": {
      "example.com": {
        "enabled": true,
        "mode": "custom",
        "params": {
          "category": "手机示例",
          "value": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1"
        }
      },
      "app.example.com": {
        "enabled": true,
        "mode": "append",
        "params": {
          "category": "测试标记",
          "value": "MyApp/1.0"
        }
      },
      "random.example.com": {
        "enabled": true,
        "mode": "random",
        "params": {
          "pool": "custom:随机示例",
          "strategy": "page"
        }
      },
      "paused.example.com": {
        "enabled": false,
        "mode": "custom",
        "params": {
          "category": "测试",
          "value": "ExampleAgent/1.0"
        }
      }
    },
    "userCustomData": {
      "手机示例": [
        "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1"
      ],
      "随机示例": [
        "ExampleAgent/1.0",
        "ExampleAgent/2.0"
      ],
      "测试": [
        "ExampleAgent/1.0"
      ]
    },
    "userAppendData": {
      "测试标记": [
        "MyApp/1.0"
      ]
    },
    "resourceDomainFallback": false
  }
}

این نمونه یک UA سراسری داخلی و چهار قاعده دامنه تنظیم می‌کند. قواعد زیردامنه مشخص‌تر مانند app.example.com بر example.com اولویت دارند؛ قواعد متوقف‌شده در تطبیق مؤثر شرکت نمی‌کنند و قاعده دامنه والد یا سراسری ممکن است جای آن‌ها اعمال شود. شناسایی UA نمونه در وب‌سایت واقعی به خود وب‌سایت بستگی دارد.

05فیلدهای سطح بالا و رفتار جایگزینی

فیلد نمونه کاربرد
version 2 الزامی. نسخه جدید فقط عدد 2 را می‌پذیرد.
type "ua-switcher-config" الزامی. شناسه نوع پیکربندی است و باید دقیقاً با این رشته مطابقت داشته باشد.
timestamp "2026-11-16T06:00:00.000Z" الزامی. از زمان UTC با میلی‌ثانیه و Z استفاده کنید؛ فقط برای ثبت است و زمان اعمال قاعده را تعیین نمی‌کند.
data { ... } الزامی. شیء نگهدارنده پیکربندی کامل که همه فیلدهای جدول زیر را دارد.
فیلدهای data قالب درست رفتار وارد کردن در این نسخه
globalRule یک شیء قاعده یا null شیء قاعده جای قاعده سراسری فعلی را می‌گیرد؛ null قاعده سراسری فعلی را پاک می‌کند.
domainRules { "域名": 规则对象 } کل شیء جایگزین قواعد دامنه قبلی می‌شود؛ {} آن‌ها را پاک می‌کند.
userCustomData { "分类": ["UA", ...] } کل شیء جایگزین کتابخانه UA سفارشی قبلی می‌شود؛ {} آن را خالی می‌کند.
userAppendData { "分类": ["追加文本", ...] } کل شیء جایگزین کتابخانه متن الحاقی قبلی می‌شود؛ {} آن را خالی می‌کند.
resourceDomainFallback true یا false مقدار بولی JSON: روشن یا خاموش کردن قاعده جایگزین دامنه منبع.

هر پنج فیلد الزامی‌اند و جز globalRule نمی‌توان از null استفاده کرد. فیلدهای مفقود یا ناشناخته و کلیدهای تکراری JSON رد می‌شوند؛ پیکربندی قدیمی یا ناقص نیز وارد نمی‌شود. قواعد دامنه و هر یک از دو کتابخانه به صورت کامل جایگزین می‌شوند: مثلاً domainRules دارای تنها یک دامنه، قواعد دامنه دیگر موجود در مرورگر مقصد را نیز جایگزین می‌کند. بهتر است فایل واقعاً صادرشده از نسخه جدید را مبنای ویرایش قرار دهید و همه موارد لازم را نگه دارید.

قاعده جایگزین دامنه منبع تنها زمانی ممکن است بر اساس دامنه مقصد درخواست منبع اعمال شود که صفحه اصلی UA مؤثر در سطح برگه، دامنه یا سراسری نداشته باشد؛ این به معنی اولویت همه منابع میان‌دامنه‌ای بر قاعده صفحه اصلی نیست.

06نوشتن شیء قاعده

قاعده سراسری و هر قاعده دامنه از ساختار یکسان استفاده می‌کنند:

JSON
{
  "enabled": true,
  "mode": "custom",
  "params": {
    "category": "常用",
    "value": "ExampleAgent/1.0"
  }
}

enabled: true به معنی فعال و false به معنی متوقف است. mode فیلدهای params را تعیین می‌کند:

6.1 UA داخلی: builtin

JSON
{
  "enabled": true,
  "mode": "builtin",
  "params": { "os": "Windows", "uaKey": "Edge 125 (Latest)" }
}

os و uaKey باید دقیقاً با کلیدهای ازپیش‌تنظیم‌شده داخلی همان نسخه افزونه مطابقت داشته باشند؛ ممکن است با متن ترجمه‌شده نمایش‌یافته در رابط برابر نباشند. مطمئن‌ترین روش انتخاب پیش‌تنظیم در رابط، صادر کردن پیکربندی و کپی params مربوط است. با تغییر فهرست پیش‌تنظیم‌ها در نسخه‌های مختلف دوباره بررسی کنید.

6.2 UA سفارشی: custom

JSON
{
  "enabled": true,
  "mode": "custom",
  "params": { "category": "常用", "value": "ExampleAgent/1.0" }
}

value رشته کامل UA است. category برای دسته‌بندی و ویرایش در رابط استفاده می‌شود؛ بهتر است این مقدار در دسته هم‌نام در userCustomData نیز باشد. هنگام اعمال قاعده، value خود قاعده خوانده می‌شود؛ وارد کردن دستی قاعده این مقدار را خودکار به کتابخانه سفارشی اضافه نمی‌کند.

6.3 متن الحاقی: append

JSON
{
  "enabled": true,
  "mode": "append",
  "params": { "category": "应用标记", "value": "MyApp/1.0" }
}

افزونه پس از UA اصلی مرورگر فعلی یک فاصله می‌گذارد و سپس value را اضافه می‌کند. بهتر است این متن را در دسته هم‌نام در userAppendData نیز نگه دارید؛ وارد کردن قاعده فهرست را خودکار پر نمی‌کند.

6.4 UA تصادفی: random

JSON
{
  "enabled": true,
  "mode": "random",
  "params": { "pool": "custom:随机示例", "strategy": "page" }
}

strategy باید "page" (انتخاب در هر بار بارگذاری کامل صفحه) یا "tab" (حفظ بر اساس قاعده و برگه) باشد. انتخاب تصادفی می‌تواند تکراری باشد؛ یکسان بودن دو نتیجه پیاپی لزوماً به معنی انتخاب نشدن دوباره نیست.

مقادیر رایج pool:

مقدار منبع انتخاب تصادفی
all همه UAهای داخلی، سفارشی و ساخته‌شده از متن الحاقی
builtin همه UAهای داخلی
builtin_desktop، builtin_mobile، builtin_legacy دسته‌های داخلی دسکتاپ، موبایل یا دستگاه قدیمی
builtin_gaming، builtin_smarttv، builtin_communication، builtin_social دسته‌های داخلی متناظر
custom UA در همه دسته‌های سفارشی
custom:分类名 UA دسته مشخص‌شده در userCustomData
append_all UA متناظر با همه متن‌های الحاقی
append:分类名 UA متناظر با متن الحاقی دسته مشخص‌شده در userAppendData

نام دسته پس از دونقطه باید با کلید کتابخانه مطابقت داشته باشد. قاعده تصادفی فعال باید گزینه قابل استفاده داشته باشد وگرنه فایل رد می‌شود.

07بررسی هنگام ویرایش دستی

  • برای کلید domainRules دامنه بنویسید، مانند example.com و shop.example.com؛ https://، مسیر، درگاه یا فاصله ننویسید. قواعد دامنه با زیردامنه‌های پایین‌تر نیز مطابقت دارند؛ *.example.com در نسخه فعلی خود example.com را نیز شامل می‌شود و به معنی «فقط زیردامنه» نیست.
  • نام دسته می‌تواند چینی باشد، باید رشته‌ای غیرخالی باشد و نباید نویسه کنترلی یا کنترل خطرناک متن دوجهته داشته باشد؛ __proto__، prototype و constructor نمی‌توانند نام دسته باشند. بهتر است برای UA و متن الحاقی از نویسه‌های ASCII قابل چاپ استفاده کنید؛ خط جدید، tab یا نویسه کنترلی دیگر در آن‌ها قرار ندهید؛ هر UA حداکثر 4096 نویسه دارد. گیومه دوتایی ASCII و بک‌اسلش در متن باید طبق قواعد JSON گریز داده شوند.
  • هر دسته متناظر با آرایه‌ای از رشته‌هاست، مانند "常用": ["Agent/1.0", "Agent/2.0"]. حتی با یک مورد نیز کروشه‌ها را حفظ کنید. دسته خالی را می‌توان [] نوشت.
  • true، false و null نباید داخل گیومه دوتایی قرار گیرند؛ "false" رشته است، نه مقدار بولی.
  • فایل باید UTF-8 و JSON معتبر باشد و کلید تکراری مجاز نیست. افزونه ساختار، نوع فیلد، قواعد، نام پیش‌تنظیم و مجموعه تصادفی را هم بررسی می‌کند؛ نحو درست تضمین نمی‌کند که قاعده قابل استفاده باشد.

فایل پیکربندی می‌تواند UA ارسالی مرورگر به وب‌سایت را تغییر دهد. HTTPS از انتقال محافظت می‌کند اما تضمین نمی‌کند پیکربندی ارائه‌شده سرور مطابق خواست شما باشد؛ فقط فایل منابع قابل اعتماد را وارد کنید، پیش از تأیید محتوا را بررسی کنید و پس از تازه‌سازی صفحه مقصد نتیجه واقعی را بسنجید.

08پرسش‌های متداول

مشکل روش بررسی
پیام نادرستی قالب فایل UTF-8، نحو JSON، کلیدهای تکراری، نسخه، فیلدهای الزامی و نوع قاعده را بررسی کنید؛ از فایل صادرشده نسخه جدید به عنوان الگو استفاده کنید.
بارگذاری راه دور شکست می‌خورد گواهی HTTPS، پیوند مستقیم، شبکه و محتوای پاسخ را بررسی کنید؛ تغییر مسیر، ورود با Cookie و HTTP مجاز نیست.
پس از وارد کردن تعداد قواعد کم شده است قواعد دامنه و هر دو کتابخانه به صورت کامل جایگزین می‌شوند؛ از پشتیبان پیش از وارد کردن بازیابی کنید یا موارد لازم را به فایل جدید اضافه کنید.
قاعده سراسری خالی وارد شده اما صفحه هنوز UA دیگری دارد قواعد برگه موجود یا قواعد دامنه منطبق را بررسی کنید؛ ممکن است بر قاعده سراسری اولویت داشته باشند.
پیام موفقیت نمایش داده می‌شود اما UA درست نیست فعال بودن قاعده، معتبر بودن محتوا، وجود گزینه در مجموعه تصادفی و وجود قواعد برگه یا دامنه با اولویت بالاتر را بررسی کنید و صفحه را تازه‌سازی کنید.
هنگام وارد کردن داده زیاد خطای ذخیره‌سازی رخ می‌دهد فایل و ذخیره‌سازی همگام مرورگر هر دو محدودیت اندازه دارند؛ قواعد یا فهرست‌ها را کوچک کنید، دوباره امتحان کنید و پیکربندی موجود را بررسی کنید.
پس از تغییر فایل راه دور افزونه تغییر نمی‌کند بارگذاری راه دور وارد کردن دستی و یک‌باره است؛ نشانی را دوباره وارد، بارگذاری و تأیید کنید.