This guide is for users who already have connection details or a subscription from their provider and need to import them correctly into Shadowrocket. First, use the link prefix to tell whether it describes one connection or a remote list. Then check the address, port, authentication, and transport options, and distinguish between importing again and updating a subscription. The domains, passwords, and UUIDs shown here are illustrative placeholders, not usable connection details.
1. Share Links vs. Subscription Links: One Connection or a Remote List
ss://, vmess://, vless://, and trojan:// are share-link schemes that tell the client how to parse the characters that follow. Each link usually describes a single connection: a server address, port, authentication details, and any required transport options. When you import one, Shadowrocket saves those fields locally. The link itself generally does not keep fetching remote changes.
A subscription link is usually an https:// address. The client requests that address and reads the connection list returned by the server, then parses it using supported formats. Subscription paths have no universal naming standard, so the presence of /sub alone does not tell you what a URL is for. A regular web page, login page, or subscription response can all use HTTPS. Refer to the information provided by your existing provider and the actual response.
| What to check | Single share link | Subscription link |
|---|---|---|
| Typical prefix | ss://、vmess://、vless://、trojan:// | Usually https:// |
| What it contains | One connection's address, port, and authentication details | An address for a remote list, possibly with a token |
| What import does | Parses the link and creates a local entry | Fetches remote content and creates entries in the subscription |
| How to apply changes later | Edit the local fields or get a new link and import it again | Update the subscription to fetch the remote list again |
| Sensitive information | Password, UUID, and server details | The full subscription URL, especially access credentials in its path or query parameters |
For example, https://example.com/sub?token=xxxx illustrates the form of a subscription URL. It is not a service endpoint or a usable subscription. A subscription can contain connections using multiple protocols, not just multiple addresses for one protocol. “Subscription” describes how connections are fetched and updated; it is not a network transport protocol.
2. ss://: Check the Shadowsocks Encryption Method and Password
A common Shadowsocks share-link format puts the encryption method and password in the user information, followed by @ and the server address and port. SIP002-formatted links can encode the user information with Base64URL. Older formats that encode more fields together are also in use. So you cannot assume every ss:// link can be split at a single @.
ss://[email protected]:8388#SS%20Demo
Decoded example user information:
aes-128-gcm:passwordaes-128-gcmis the example encryption method and must match the server configuration. Do not substitute another method just because its name looks similar.passwordis a sample password. Use the actual password exactly as provided, including capitalization and special characters.server.example.comis an example domain, and8388is an example port. Shadowsocks does not require every connection to use this port.#SS%20Demois a link fragment, typically used as a remark;%20represents a space. Changing the remark generally does not change the authentication details.- If the original link includes a
pluginparameter, check whether the corresponding plugin and its options are supported. Ignoring them can result in a link that imports successfully but cannot connect.
After importing, open the entry's edit screen in Home and check the protocol type, address, port, encryption method, and password. A successfully created entry only confirms that parsing worked. You still need to test whether the server accepts the password and whether the port is reachable.
3. vmess://: Understand the Encoded JSON Fields First
A common vmess:// share link contains a Base64-encoded JSON object after the scheme. The encoded data usually includes fields such as the address, port, user ID, transport, and TLS settings. The example below shows a decoded object for reference; it is not a complete share link that you can paste to import.
{
"v": "2",
"ps": "VMess Demo",
"add": "server.example.com",
"port": "443",
"id": "123e4567-e89b-42d3-a456-426614174000",
"aid": "0",
"scy": "auto",
"net": "ws",
"type": "none",
"host": "edge.example.com",
"path": "/demo",
"tls": "tls",
"sni": "edge.example.com"
}| Field | Purpose and what to check |
|---|---|
add / port | Connection address and port. The example uses 443; not every VMess service uses this port. |
id / aid | User UUID and alterId. The example uses an alterId of 0. Use the value in your actual connection details; do not change it arbitrarily. |
scy | VMess encryption option. This is not the TLS switch or the Shadowsocks method field. |
net / host / path | The example uses WebSocket. Host and path must match the server requirements; do not change the path's capitalization or leading slash arbitrarily. |
tls / sni | Whether TLS is enabled and the server name used for the TLS handshake. The SNI may differ from the connection address. |
v / ps | Share-format version marker and remark. The v here is not the Shadowrocket app version. |
These fields are used in one common share format; not every generator produces exactly the same JSON. Check the parsed fields after import rather than relying on the remark. If your connection details require WebSocket and TLS but the imported entry is missing a path or has the wrong TLS setting, first check whether the original link was truncated, then confirm the format and parameters with your existing provider.
4. vless:// and trojan://: Query Parameters Are Part of the Connection
Common VLESS and Trojan share links use a more readable URI format: authentication details come before @, the address and port follow it, and security and transport options come after the question mark. Their authentication fields differ: VLESS commonly uses a UUID, while Trojan uses a password. You cannot convert one protocol to the other by changing only the prefix.
vless://[email protected]:443?encryption=none&security=tls&type=ws&host=edge.example.com&path=%2Fdemo&sni=edge.example.com#VLESS%20Demo
trojan://[email protected]:443?security=tls&type=tcp&sni=edge.example.com#Trojan%20Demo- Check the authentication details first. The UUID in the VLESS example and
demo-passwordin the Trojan example are illustrative values; use the original details when importing. - Next, check
server.example.com:443. Port 443 is just the specific example here. Do not override another port supplied by your provider on the assumption that TLS usually uses 443. - Check
security=tlsandsni. They affect the TLS handshake and certificate checks; they are not just display names. - Check
type=wsortype=tcp. In the VLESS example,hostandpathare WebSocket settings;%2Fdemodecodes to/demo. - Keep any other required parameters from the original link. If the connection details include flow or other security-related fields, check that the client recognizes them. Do not remove them based on this simplified example.
In the VLESS example, encryption=none is the VLESS encryption option. It does not mean the example lacks TLS protection; protocol authentication, transport, and TLS are separate layers. Trojan typically relies on TLS, so the certificate name and trust status matter too. If you encounter a certificate error, check the address, SNI, and server certificate instead of disabling certificate verification.
In short: Check authentication, transport, and TLS after importing
If the entry appears but the connection fails, compare the UUID or password, port, type, path, and SNI one by one. A matching remark does not prove that the connection parameters match. Change only fields confirmed to be incorrect, then test again before changing anything else.
5. Import in Home: Choose a Single Link or a Subscription
First, identify what kind of connection details you have. Home is where you manage and select connection entries; Config is for configuration files and rules; Settings is for app preferences. A connection-list subscription is not a rule configuration file. Adding a subscription URL through Config's configuration-file option does not import it as a connection subscription.
Already have a subscription? Import it with Subscribe
RecommendedIn Home → +, set Type to Subscribe, enter the subscription URL you already have, and save. Then check whether the remote list was fetched successfully. This is recommended for users who already have a subscription and want to keep it linked for future updates.
Best for: An existing remote connection list that needs to reflect changes to addresses, ports, or credentials
Have a single connection? Import its share link
Copy the complete share link, return to Shadowrocket, and confirm the clipboard import prompt. You can also scan a QR code from connection details you already have. When import is complete, open the entry and check its fields rather than just confirming its name.
Best for: Saving one specific connection or checking its parameters
Have structured details? Enter them manually
In Home → +, select the appropriate Type, enter the address, port, and authentication details from the information you already have, and check the transport and TLS options. Creating a local entry manually does not link it to subscription updates.
Best for: A list of connection fields or pinpointing a difference in how a share link was parsed
- Copy the complete link from the original source. Do not include Chinese quotation marks, end punctuation, chat instructions, or code fences.
- After saving, return to Home and check whether you see an individual entry or a subscription with entries beneath it. Seeing the subscription name alone does not confirm that its list was fetched successfully.
- Open a connection's edit screen and check its type, address, port, and authentication fields. If it uses WebSocket or TLS, check those options as well.
- Select the connection you want to test. The first time you turn on the connection switch, follow the system prompt to authorize adding a VPN configuration, then test access to your destination.
A QR code is just another way to carry a link, not an additional protocol. If it contains a subscription URL, treat it as a subscription after import. If it contains a single ss:// link, scanning it does not give it remote update capabilities. Check the actual interface on iPhone or iPad; for system requirements, refer to the App Store listing.
6. Updates and Troubleshooting: Tell Fetch Failures from Connection Failures
Updating a subscription requests the remote list again. It does not update the Shadowrocket app or refresh rules in Config. Remote entries may be added, removed, or replaced; do not assume every local change to a subscription entry will survive the next update. For comparison tests, record the fields and results before making changes.
Two ways to manage connections: local entries and remote subscriptions
Single local connection
- If the address or password changes, get a new share link and import it again, or edit the existing fields.
- After importing again, check for duplicate entries with the same name and distinguish them by address and port.
- Remove the old entry only after a successful test, so you do not accidentally delete the connection you are using.
Existing remote subscription
- In Home, update the relevant subscription and check whether its entries were fetched successfully.
- After updating, check whether the currently selected connection is still there and whether its parameters have changed.
- If the access credentials have changed, replace the subscription URL first, then fetch the list again.
Local edits change the fields currently saved on your device; a subscription update fetches remote details. Neither replaces the other.
When troubleshooting, check three separate stages: whether the URL request succeeds, whether the response can be parsed, and whether the resulting connection works. For example, HTTP 401 or 403 often indicates an access authorization issue, but check the provider's response details. An HTTP 200 response could still be a login HTML page. If entries appear but websites do not load, continue by checking the connection, Global Routing, and rules in Config instead of repeatedly importing the same link.
Why didn't a new entry appear in Home after I copied the link?
First, make sure the link starts with the complete scheme and contains no line breaks, full-width colons, or chat notes. If the system asks whether to allow pasting from another app, allow it if needed. Copy the original link again and retry the import. Do not edit Base64 data by hand to troubleshoot.
A subscription update timed out. Does that mean all its connections are down?
Not necessarily. First check whether your current network can reach the subscription URL. If you need an existing working connection to fetch it, check Update via Proxy under Settings → Subscribe, select a working connection in Home, turn on the connection switch, and try updating again. This option changes how the update request is routed; it will not fix an expired token or an invalid response format.
The import succeeded. Why can't I open websites?
First check the selected entry's address, port, password or UUID, then check its TLS and transport options. Next, review Home → Global Routing: Direct sends traffic directly; Proxy sends proxy-capable traffic through the selected proxy policy; Config applies the current configuration rules; Scene applies the configured scene. If needed, temporarily switch to Proxy for comparison, then restore the previous setting when testing is complete.
I changed the remark, but it reverted after updating the subscription. What should I do?
First check whether the remote list still provides the old remark. A subscription update may recreate or overwrite entries; changing a local remark does not change the remote version. To preserve comparison notes, record the test separately or save it as an independent entry, noting that it will no longer update automatically with that subscription.
Can I share a real link or QR code so someone else can check it?
Do not share complete connection details publicly. When reporting an issue, provide the protocol type, port, transport, and a redacted error message. Hide the password, UUID, token, full URL, and QR code. If the details have already been exposed, change the relevant credentials through your existing provider's management portal, then update the local connection or subscription.