Shadowrocket
Subscriptions and Servers

1. Subscribe: Import an Existing Subscription

First, make sure you have a subscription URL

A subscription URL points to a server list that can be retrieved again; it is not the same as one server in that list. After import, Shadowrocket parses the response and creates the corresponding entries. Refreshing later retrieves the URL again. Before importing, confirm whether you have a subscription link, a single-server share link, or server details that need to be entered manually. Do not identify a link by its length alone, and do not mistake an account page opened in a browser for a subscription URL. This guide assumes you already have your own subscription.

Subscription URLs often include query parameters that may contain access credentials. Copy the complete URL, including its scheme, path, and parameters. Avoid including quotation marks, line breaks, a Chinese full stop, or explanatory text added by a chat app. The example below is for format recognition only and cannot be used to connect. Do not include a real URL in public screenshots, shared notes, or support requests. Even if it looks like an ordinary web address, treat it as sensitive information.

https://example.com/sub?token=xxxx

Add a Subscribe entry from Home

From Home, use the add option to open Add Server, select Subscribe, then enter the complete URL in the URL field and add a recognizable name in the remarks field. Before saving, make sure the URL is intact, especially any trailing parameters. The layout may vary, so follow the types and fields shown in your app. Do not enter a subscription URL in the Address field for a regular server. After saving, wait for the fetch to finish, then check the list.

Check the result in three steps: confirm that the subscription group appears, check that it contains server entries, then inspect one entry's protocol, address, and port against your existing documentation. These checks correspond to creating the subscription, parsing its response, and validating its contents; none can replace another. Seeing the subscription name only confirms that the local entry was saved. A populated list does not mean every server can connect. After the first import, keep your existing working entries until you have verified the connection, then consider organizing the list.

Distinguish fetch failures from connection failures

If no servers appear after saving, first check that the URL was copied in full, then confirm that your current network can reach it. If a browser shows a sign-in page, an informational page, or an error, the response may not be a server list the app can parse. Text appearing in a browser does not prove the format is valid. If something looks wrong, check your subscription documentation; do not keep changing the protocol type in an attempt to turn a web page into a server entry. For failures during fetching, check the URL and response first, not the server's encryption settings.

If an entry appears but cannot connect, check its server fields and network reachability. The subscription may have returned an expired entry, or a specific entry may be missing required parameters. Note the subscription group, the failed entry's protocol, and the stage at which the error occurred; you do not need to share the full URL. When every entry fails, check the shared network conditions and list contents first. For a single failed entry, compare its settings with the others.

For easier management, keep a local record for each subscription noting its purpose, where the original URL is stored securely, and any manual changes. Do not put the URL in a public note. This helps you tell subscription-generated entries from manually created ones when updating or moving to a new device. If you find duplicate subscriptions, do not delete either group right away. Compare their URLs and contents first to see whether only the remarks differ, then follow the steps in Chapter 8.

2. Add Server: Manual Fields and Protocol Settings

Choose Type, then enter the shared fields

Manual setup is for when you already have complete server details and need to verify each field. In Add Server, choose Type first, since each protocol displays different settings. With the wrong type, even a seemingly correct address and password will not make a valid connection. Do not guess the protocol from the port number; a port does not identify a protocol. The same address may host different services, so verify the protocol, port, authentication method, and transport settings as a set against your existing server configuration.

For common fields, Address is usually the server's domain name or address, Port is the server's listening port, and remarks are just for identification. Unless the field explicitly requires a full URL, do not put a web page path or an entire share link in Address. After pasting, check for leading or trailing spaces, and make sure the port contains no colon. Keep passwords, identifiers, and other credentials exactly as provided. Case, hyphens, and special characters can affect authentication; do not change or fill them in for readability.

Check authentication and transport for the selected protocol

Shadowsocks requires the correct encryption method and password. Do not enter authentication details for another protocol. VMess and VLESS identifier fields may look similar, but they do not mean the same thing. Check authentication, transport, and security settings against the corresponding existing configuration. Trojan is often used with TLS settings; entering only the password may leave certificate-name requirements unchecked. For Hysteria2, verify authentication and TLS parameters against your existing details rather than inferring server settings from the protocol name.

WireGuard uses parameters with distinct roles, including keys, peers, and network ranges; it should not be treated as a simple address-and-password setup. When importing or entering details, distinguish the local private key from the peer's public key. Never share the private key when asking for help. For HTTP and SOCKS5, check whether the server requires a username and password, and make sure you select the correct protocol. These protocol names are included to help identify fields; they do not mean the same set of parameters can be reused across types.

Keep security checks enabled; test after changing one setting

The TLS certificate verification name may differ from the server's connection address. SNI, Host, and Path are also separate settings, not one general “domain” field. For authentication failures, check the connection target, transport entry point, and certificate identity separately. Do not disable certificate verification as a routine fix, and do not add transport parameters unless you know what they are for. If your server documentation does not specify an optional field, leave a reasonable default in place and verify whether the field is actually required.

After saving, select this manual entry by itself and test it first. If you need to make changes, change one category of fields at a time and record the results before and after. Changing the password, port, transport, and rules all at once makes it difficult to identify the cause of a failure. Before editing a subscription-generated entry, consider whether a refresh may overwrite your changes. If you need to keep a local test configuration, use the app's copy feature if available and give the separate entry a clear name. Do not rely on temporary edits to a subscription entry to persist.

After a manual entry connects, confirm that it is the entry you intended to use, not an earlier connection that was already working. Disconnect, select the new entry, reconnect, and test a service you are authorized to access. If you still have questions about a field, compare it with the original server details one by one. For common issues, see the FAQ. Do not substitute random parameter combinations for checking the configuration.

3. Scan QR Code: QR and Clipboard Imports

Scanning is an input method, not a configuration type

A QR code may contain a single share link, a subscription URL, or plain text. Before using Scan QR Code, confirm that the code contains a configuration you already have and decide whether you expect to import one server or a subscription group. A successful scan only means the text was recognized; it does not confirm that all protocol fields are present or that the server has passed a connection test. If the result is unexpected, check what kind of content the code contains before saving or turning on the connection.

Open Scan QR Code in the app and follow the system prompt to decide whether to allow camera access. Position the complete QR code within the viewfinder, avoiding cropped edges, glare, and excessive zoom. For a QR code saved on the device, use a photo-scanning option only if the current interface provides one; do not assume every layout offers the same option in the same place. Use the original image from your own saved materials whenever possible, rather than a blurry copy that has been forwarded, compressed, or stitched together multiple times.

If scanning opens a parameter preview, check Type, address, port, and remarks before saving. A QR code can encode several pieces of information, so a familiar remark alone does not prove that the content is correct. Remarks are labels for identification, not a way to verify a server's identity. If the scan returns a subscription URL, follow the subscription flow to create it and fetch the list. If it returns a single protocol link, follow the server import flow. The two have different update capabilities.

Clean up text boundaries before importing from the clipboard

When copying a share link, select only the link itself. Do not include explanatory text, numbering, list bullets, or quotation marks. After opening Shadowrocket, if you see a prompt to read the clipboard or import content, verify its source and expected result before proceeding. If no prompt appears, use the corresponding import option in the current interface. Clipboard permissions can affect the process. No import prompt does not mean the link is invalid, and repeatedly copying other sensitive content is not a good way to test it.

Check multiline clipboard content carefully. A subscription response may contain a complete encoded list of entries, while a chat message may simply concatenate multiple links; the same import option may not handle both. If a bulk import is not recognized, test one complete, clearly identified share link first, then check the original content format. Do not repeatedly decode, add line breaks, or replace special characters without understanding the encoding. These changes can corrupt content that was originally valid.

Verify the import after saving

An import check should include at least three steps: confirm the new item appears in Home, inspect key fields in its details, then test the connection. If scanning succeeds but no item appears, check whether you are still on an unsaved edit screen or whether the content was imported as a subscription group rather than a standalone server. If the list is long, use the remark you just set to find the item. Avoid scanning repeatedly and creating several indistinguishable copies. Importing the same content again usually will not fix its parameters.

If recognition fails before saving, check the image, protocol prefix, and text format. If saving succeeds but the connection fails, check authentication, transport, and server reachability. This distinction helps narrow down the issue. For links reformatted by someone else, compare them with your securely stored original, paying particular attention to full-width characters, automatic line breaks, and the trailing text. A short text preview in the copy interface may not represent the complete link.

After importing, handle temporary screenshots and clipboard history carefully. If a QR code or link has been exposed somewhere you cannot control, follow the original service's credential-management process to replace the affected information. Deleting the imported entry from your device does not invalidate exposed credentials. For more help identifying formats, continue to the next chapter. If the issue involves system permissions, start with the authorization steps in the first-connection guide so you do not confuse a permissions problem with an import problem.

4. Share Links: Formats and Configuration Boundaries

Check the prefix first, then identify the content

Share links package protocol parameters into copyable text to reduce manual entry errors. Common prefixes include ss://, vmess://, vless://, trojan://, and hysteria2://. These prefixes help the app choose a parsing method, but they do not reveal every transport or authentication detail. A single-server share link usually describes one server entry; a subscription URL retrieves a list of entries again. Saving a single-server share link does not provide ongoing subscription updates.

Different formats may use encoded authentication details, query parameters, and remarks after a hash sign. Encoding is a way to represent data, not a security measure; anyone with the complete link can usually access its parameters. Some links contain percent-encoded text, and non-English remarks may also be encoded. Keep the original text when troubleshooting. Do not remove equals signs, percent signs, or separators just to make the string “look right,” and do not mistake a trailing remark for part of the password.

Compatible parameters do not mean the content is identical

Links for the same protocol may express fields differently, and the importer may not support every combination of optional parameters. To confirm an import is complete, inspect the imported fields rather than relying on a success message. Settings such as transport type, TLS, SNI, Host, and Path may be missing even if a server entry was created, preventing the expected connection. If the original link has extra parameters, verify whether the app recognized each one. Do not map unfamiliar fields to similarly named options at random.

Importing a share link usually adds one server entry; it does not replace the entire Config. The server determines where to connect, while rules determine how requests are handled. They work together. The Config routing mode under Global Routing applies the current rules to requests; Proxy and Direct behave differently. When troubleshooting, check the current mode first, then review the rules if needed. This helps avoid mistaking a rule that sends traffic direct for a share link that failed to import.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

The example above explains how rules and server entries differ; it is not a complete configuration recommendation. DOMAIN-SUFFIX matches domain suffixes, GEOIP checks the region associated with an address, and FINAL provides a fallback. Rule order affects which rule matches. PROXY and DIRECT are policy keywords, not server passwords, and should not be entered in Add Server authentication fields. Before using a rule, understand its scope and check its location in your existing Config.

Be clear about what you are sharing

Before sharing or saving materials, confirm whether you are exporting one server, a subscription URL, or a rule configuration. Each restores something different: a server link rebuilds connection parameters, a subscription URL fetches a list again, and a rule file restores request-handling logic. Backing up only one does not mean your entire setup can be restored. If someone only needs to troubleshoot rules, share a redacted rule snippet rather than the full connection credentials.

If you are unsure about a format, read Share Links vs. Subscription URLs, then check the original material to confirm what you are importing. Do not rewrite a share link as an ordinary web address or force a protocol prefix onto an HTTPS subscription URL. Format conversion is useful only when you understand the fields and the target format supports them. Replacing a prefix manually does not convert the protocol; it can instead cause subtle parameter loss.

5. Update Policy: Refreshing and Handling Failures

Understand what a subscription refresh changes

Refreshing a subscription retrieves the server list again. It does not speed up the current connection or update the app itself. If the remote list changes, a refresh may add or remove entries, change names, or replace parameters. Local edits to subscription entries may also be overwritten by remote content. So do not assume that changes to remarks, ports, or transport settings on important entries will be permanent. Before refreshing, note any differences you need, then decide whether to correct the original configuration or keep a separate manual entry.

For routine use, start with one manual refresh, check for a clear error, then review any changes to the list. Subscription actions may be available through a list gesture or an edit option; follow the controls shown in your current interface. After refreshing, check the subscription group and the entry you had selected, not just whether a prompt disappeared. If the current server was removed or renamed, select a valid entry again and check the connection. Refreshing the list and switching the active connection are separate operations and may not happen together.

Set automatic updates to match how you use the app

Check for automatic update options in the subscription settings actually available in the app. An update triggered when you open the app does not mean it will run at exact intervals in every background state. System scheduling, network conditions, and whether the app is running can all affect timing. If you need to confirm the list before an important session, check it manually rather than guessing whether a background refresh occurred. Do not use a date in the subscription name to determine when it was last fetched; the name may be static text.

Refreshing more often does not make a subscription more reliable. Repeated requests to the same URL in a short time may run into network fluctuations, access limits on the remote end, or cached responses. A better approach is to fetch once, then read the error and identify which stage failed instead of tapping repeatedly until the result changes. If an issue appears after an automatic update, note whether it was a fetch failure, a list change, or a connection failure; each calls for a different response. A secure backup of important local entries is more useful than shortening the refresh interval.

Troubleshoot the URL, network, and content in turn

First, check the URL: make sure the original link is not truncated, its query parameters are intact, and it has not been replaced with a web page URL. Do not use a public online tool to test links with sensitive parameters; compare the original text locally instead. If credentials have been changed, the old URL may still be saved locally. Simply reopening the app will not update it. Confirm how the old and new URLs relate before editing the subscription entry, so you do not mix up subscriptions for different purposes.

Next, check the network. Reaching the subscription server from your current connection and connecting to a server imported from the subscription are separate issues. If you see a timeout or DNS resolution error, try again on another network you can use, keeping the URL unchanged for comparison. Do not change the network, URL, and rules all at once, or you will not know which change made a difference. If you think the current routing settings are affecting the fetch, note them first and test carefully. Do not treat a temporary switch as a permanent configuration.

Finally, check the content. A successful request does not guarantee that the response is a valid list. The remote service may return an error message, a sign-in page, empty content, or an unsupported format. Keep your existing working list; do not delete everything just to “start fresh.” Check the format requirements in your service documentation and record the error type without sensitive details. If only one subscription is affected, check its URL and response first. If all groups are affected, check shared network conditions and the app state.

If a successful update changes the result, first check whether the server entry was replaced, then verify the selected entry and Global Routing, and only then review the rules and target request. Brief notes from before and after the issue can prevent repeated tests. For details on manual refreshes and automatic updates when opening the app, see How to Update Subscriptions. To retrace the parameters, follow the field-checking steps in Chapter 2.

6. Organizing Multiple Subscriptions: Groups and Names

Keep source information separate from usage notes

When managing multiple subscriptions, the goal is not simply to shorten the list. You should be able to tell where each entry came from, what a refresh will change, and which entry is currently selected. Subscription groups track the source, server remarks identify entries, and local notes record changes. Do not cram all three into one long name, or rename every group identically for a consistent look. Matching names increase the risk of selecting the wrong item; matching URLs may indicate duplicate objects. Check these separately.

Use short, stable names that describe each subscription's purpose, and keep the original URL and change notes in your own secure records. You can retain the server's existing labels and add an easy-to-recognize local marker to independent manual entries. Do not put full passwords, private keys, or subscription tokens in remarks. Remarks appear in lists, screenshots, and exports, so they are not suitable for storing credentials. Names should not promise fixed performance; a speed result from one test will not remain true forever.

Identify duplicates before merging

Two entries with the same domain and port are not necessarily duplicates; they may differ in authentication, transport, security, or routing purpose. Conversely, entries with different names may have identical parameters. When organizing, compare the protocol and address first, then authentication and transport fields, and finally the subscription group. Compare credentials locally; do not copy them into public text. Keep only one object if you have confirmed the entries mean the same thing and understand how future updates will affect it.

If duplicates came from importing the same subscription more than once, compare the subscription URLs first rather than deleting servers one by one. Duplicate subscription groups may generate similar lists again on the next refresh. Before making changes, identify the group currently in use, back up anything you need, then delete the extra group. If names are merely similar within one group, check the remote list itself. Do not delete entries with potentially different parameters just to make the interface look tidy.

Check selection, sorting, and policy separately

A change in list order does not mean the active connection has switched. Manual sorting, sorting after tests, and reimporting can all change where entries appear, but you still need to confirm which entry is selected. When organizing a long list, note the current subscription group and server name first, then check them again afterward. If a remote update changes a name, use the protocol and address to identify the entry; do not rely on its remembered position. Position helps with browsing, not reliable identification.

Do not confuse the Config, Proxy, and Direct modes under Global Routing with subscription groups. Groups organize the list; routing modes determine how requests are handled. A group containing many entries does not mean the app will automatically select one for your purpose. Naming a group for a particular use does not change how rules work. To specify how requests are handled, check the rules and policies in the current Config rather than expecting a remark to change behavior.

For temporary test entries, set a cleanup condition: delete them only after reproducing the issue and saving a secure record. Do not assume an entry is permanently unusable just because one latency test was high. Before removing a subscription you no longer use, confirm you have the materials needed to restore it. Organize in small batches and check the active connection and remaining groups after each batch. Deleting, renaming, and reimporting many objects at once makes it hard to identify what caused a later issue.

You can use the same naming convention on iPhone and iPad, but check local selections, sorting, and test results on each device separately. Matching names do not prove that both devices are in the same state. For app purchases and device details, see the iPad app guide. Verify configuration migration separately in Chapter 8. This keeps names easy to recognize while allowing for differences in network conditions and local state.

7. Connectivity Test: Latency and Sorting

Understand what the test measures

Connectivity Test shows the result of a particular connection test, and the reading must be understood in the context of how the test works. Different methods may measure target reachability, connection setup, or the time taken to reach a test target through a server. These numbers are not necessarily the response time for a complete real-world request. Before testing, check the method and target in use, and keep them the same when comparing results. A low reading once does not prove higher download speeds or equal performance on every site.

Test results also depend on the current network, DNS resolution, server load, the test target's response, and timeout settings. The same entry can produce different results on different networks; do not compare readings without accounting for changed conditions. Batch tests may also send concurrent requests, so their results may differ from a single test. A practical approach is to screen entries once on a stable network, retest a few candidates individually, then verify them against your actual needs.

Test under consistent conditions before sorting

Update the subscription before testing so the list does not refresh during the test. Confirm the network and test method, then choose which entries to compare. For a long list, test by group rather than testing every entry each time. After testing, distinguish valid results from timeouts before sorting. If the app offers sorting by test results, use it as a temporary filter and keep names clear so you can still identify entries after their positions change.

Sorting by latency can narrow down the candidates, but it should not replace choosing and verifying a connection. An entry that responds quickly to the test target may perform differently for the service you actually need. Select a candidate explicitly, check Global Routing, connect, and access a service you are authorized to use. If the test succeeds but the service does not, check the rules, DNS resolution, and target response rather than repeatedly switching to the entry with the lowest number.

Separate failures by entry, group, and target

For a single failed entry, check its address, port, authentication, and transport settings, then compare them with a working entry in the same group. If a whole group fails, first check whether the current network can reach the relevant addresses, then see whether the subscription contents have changed. If every group fails, also check whether the test method and target suit the current environment. This order helps prevent accidental deletion: do not assume every entry has broken parameters until you have checked shared conditions.

If the test target responds but the actual destination does not, check whether the request followed the expected route. Rules such as DOMAIN, DOMAIN-SUFFIX, GEOIP, and FINAL in Config affect matching. If the current mode is Direct, a successful server test will not automatically route regular requests through a proxy. Use the connection or log information actually available in the app to verify the policy, but redact domains, addresses, and credentials before keeping only the relevant details.

To compare candidates, run a few tests close together on the same network and with the same method. Look for consistency instead of choosing the best-looking number from many attempts. After connecting, check whether the actual task succeeds. Do not use continuous batch testing in place of real-world verification, and account for the data and background activity tests may generate. If you are concerned about battery use, see Background Battery Use and the On Demand Trade-Off.

Keep a clear record of why you chose an entry: the network, test method, target, and result. This is more useful for troubleshooting than a sorting screenshot without context. Keep entries that timed out temporarily for observation; delete them only when you no longer need them and know how to restore them. Testing provides evidence; deletion is a configuration-management decision and should not be triggered automatically by one failure.

8. Deletion and Backups: Recovery Materials and Migration Checks

Confirm what you are deleting first

Before deleting, identify whether the object is a standalone server, a subscription-generated entry, an entire subscription group, or Config. Deleting a standalone entry usually removes its local parameters; deleting a subscription group may also affect the group and its associated list. Read each confirmation prompt carefully rather than confirming out of habit. If you delete a single server generated by a subscription, a later refresh may recreate it. That is fundamentally different from deleting the subscription itself, so first confirm exactly what you want to remove.

If you delete the entry used by the current connection, do not assume the connection state or next selection will be what you expect. Before organizing, note the current entry and disconnect. After deletion, select another entry and verify it. If you only want to hide an entry you are not using temporarily, check whether the current interface provides a suitable way to manage it. Irreversible deletion should not be your only option. Keep groups whose effects are unclear until you have made a backup.

Prepare recovery materials in layers

A reliable backup should account separately for subscription URLs, manual server parameters, and rule configurations. A subscription URL can retrieve a list again, but the remote contents may not remain the same. A single-server share link can rebuild server settings but may not cover all app settings. Config preserves rule logic, but that does not mean connection credentials are included. List the objects you actually use before backing up, then make sure each has recoverable materials. One export file does not necessarily contain everything.

If the current interface provides a share, export, or backup option, read what it includes before saving. For fields you are unsure about, inspect the exported content locally or test a restore while keeping the original intact. For manual entries, check that authentication, TLS, transport, and any special fields are included. Remarks and test screenshots are not parameter backups. Do not record only the address and port while omitting authentication details.

When saving a backup, you can add notes without credentials to describe its purpose, export scope, current rule selection, and any important manual changes. Make files easy to identify without exposing passwords or tokens in their names. If you use a storage method you trust, also consider device loss, access permissions, and clearing outdated copies. Encryption helps protect the contents, but keep the access method needed for recovery safe too. A backup is no use if you cannot open it.

Restore in stages after changing devices or reinstalling

Get the app through the App Store. For purchased items and account details, see the restore purchases guide. Check the App Store listing for system requirements and whether the purchase is universal. Being able to download the app again does not mean subscriptions, manual servers, and Config are restored automatically. On the new device, check what is already there before importing anything, so you do not duplicate a group after some data has already been restored.

Restore in this order: subscriptions, standalone servers, Config, then connection verification. After each category, check the entries and fields before moving on. A subscription list may have changed since it was first retrieved, so check the selected entry. Verify key parameters for restored manual entries. After restoring rules, confirm the active Config and Global Routing mode. Then follow the system prompts to authorize the VPN configuration and test a real connection. Seeing entries in a list does not mean migration is complete.

Keep the materials and backups on the original device until the new device has been verified. If the results differ, compare network conditions, the selected entry, and routing mode before checking parameters; do not immediately overwrite everything. If you need to roll back, restore the objects you previously recorded rather than letting an old Config overwrite new changes or an old subscription generate duplicate entries. Change one layer at a time during migration so each step is clear and reproducible.

Finally, check that each backup still matches the current setup: old copies may no longer work after credentials change, and an old rules file may no longer reflect your intended use. Securely delete sensitive copies you no longer need. Removing a local entry or file affects only your copy; it does not revoke credentials that have been exposed. If credentials were exposed, follow the original service's credential-management process. For routine tasks, return to the quick-start guide. For a specific error, continue troubleshooting by category in the FAQ.