At a glance

If you already have connection details, start with the link prefix: each of these four protocol share links describes a single server entry, while an HTTP or HTTPS subscription URL lets Shadowrocket fetch a remote list. The examples below explain the fields and encoding, then show how to import and update them on iPhone or iPad using Home and Add Server, and how to tell a parsing error from a connection failure.

Start with the link prefix: a single server entry or a subscription URL

The prefixes ss://, vmess://, vless:// and trojan:// identify the protocol; the rest of each link contains the parameters needed to connect. Importing saves those parameters locally. If the original configuration changes its address, port or credentials, the saved entry won't update automatically.

A subscription link is usually an HTTP or HTTPS URL, such as https://example.com/sub?token=xxxx. It points to a list that must be fetched, not to one server in that list. An HTTPS URL opening in a browser isn't necessarily a subscription: a login page, error page or unsupported response can't be parsed as a server list.

4
Protocol share link prefixes covered here
1
Server entry described by each protocol share link
2
Credentials to distinguish: credentials for one connection and credentials to fetch a subscription

Fields and encoding in the four share link formats

The links below use example hosts and credentials to illustrate the formats only. The example ports 8388 and 443 aren't requirements imposed by the client. For an actual setup, keep the port, transport and security parameters from the configuration you were given.

Shadowsocks: Base64URL-encoded user info in ss://

ss://[email protected]:8388#SS-demo

In this SIP002-style link, the text before @ is the unpadded Base64URL representation of aes-128-gcm:test. After decoding, the text before the colon is the encryption method and the text after it is the password. The host and port follow @, and the remark follows #. Only the specified fields are encoded; don't Base64-encode the entire link again. If a link includes plugin parameters or uses a different format, keep it intact rather than deleting fields based on this short example.

VMess: the content after vmess:// is often Base64-encoded JSON

{
  "ps": "VMess-demo",
  "add": "vmess.example.com",
  "port": "443",
  "id": "123e4567-e89b-42d3-a456-426614174000",
  "aid": "0",
  "net": "ws",
  "host": "vmess.example.com",
  "path": "/ws",
  "tls": "tls"
}

This shows the decoded content of a common VMess share link format, not a complete link you can paste directly. ps is the remark, add and port are the server address and port, and id is the UUID. This example uses WebSocket: net, host, path and tls describe the transport, WebSocket Host, path and TLS settings. Copying only the address, port and UUID won't recreate the full configuration.

VLESS: vless:// uses a UUID and query parameters

vless://[email protected]:443?encryption=none&security=tls&type=ws&host=vless.example.com&path=%2Fws&sni=vless.example.com#VLESS-demo

The UUID comes before @; connection options follow ?. Here, type=ws indicates WebSocket, path=%2Fws decodes to /ws, and sni specifies the server name used in the TLS handshake. The example uses both encryption=none and security=tls; they describe settings at different layers, so don't disable TLS just because you see none. The server address, WebSocket Host and SNI happen to match in this example, but they may differ in an actual configuration.

Trojan: trojan:// uses a password, not a UUID

trojan://demo%[email protected]:443?security=tls&type=tcp&sni=trojan.example.com#Trojan-demo

The example password is demo@pass. The @ in the credential field is written as %40 so it isn't mistaken for the separator before the address. Likewise, a # used as part of a field can't be written as the remark separator. You can compare decoded fields when troubleshooting, but import the original URI. Decoding the entire link before pasting it may change where fields begin and end.

Choose an import method in Home

Import by subscription URL (Type → Subscribe)

Recommended

On iPhone or iPad, tap + in the top-right corner of Home to open Add Server, then select Subscribe under Type. Paste the full address into the URL field and save. Return to Home to check the subscription group and its entries. If the address has query parameters, copy them along with the URL.

Best for: an existing subscription URL when you need to refresh the same group of server entries from its source.

Import by protocol share link

Copy the complete share link and open Shadowrocket. If a clipboard import prompt appears, confirm and check the new entry in Home. If you have a QR code for the same configuration, use the scanner in Home. If no import prompt appears, first check that the clipboard contains exactly one complete URI, then check whether paste access is allowed.

Best for: saving one specific entry or when you only have a protocol share link.

Keep the original string before importing

If you receive both types of address, save them separately: use the protocol URI to check an individual entry and the subscription URL to refresh a list. If you see line breaks or trailing punctuation, copy the address again from its original source instead of rearranging parameters by hand. Don't share a URI password or UUID, or a subscription URL token, publicly. Base64 is an encoding, not a way to hide credentials.

Check subscription updates, routing rules and connection tests separately

Updating a subscription requests the same URL again and parses the response; it doesn't replace a separately imported entry with the same name. Conversely, a manually imported entry that still works doesn't prove that an old subscription URL is valid. If you suspect the source has changed, note the old entry's address, port and transport, then compare them with the refreshed list. Don't compare remarks alone.

  1. Update the list first: In Home, refresh the original subscription group and check whether entries appear. If the source has changed its address or token, update the saved URL; repeatedly requesting the old address won't fetch a new list.
  2. Then check the selected entry: Once the list has entries, select the one you want to use and verify its port, credentials, TLS, SNI and transport path. A successful import only means the fields could be parsed; it doesn't confirm that the server is reachable or the credentials are valid.
  3. Finally, check routing: If the connection is established but a request isn’t taking the expected route, check Global Routing on Home. If you’re using Config, check the active rules and their order in Config. Importing a server entry does not change the rules.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

In this rule snippet, requests to example.com and its subdomains use PROXY. Other requests that don't match a rule fall through to FINAL,DIRECT. So seeing a direct connection when testing another domain doesn't mean the share link failed to import.

FAQ: parsing errors, empty lists and duplicate names

Why does importing vmess:// show a format error?

Copy the link again from the original text. Check that the prefix is intact and that the end doesn't include a period, quotation mark or ellipsis from the message. Make sure any line break is just visual wrapping, not an actual newline in the copied text. Don't remove equals signs or replace characters first; different links may use different encoding formats.

Why is Home empty even though the subscription URL opens?

Make sure you have a subscription URL, not an account page or download instructions. If the existing source returns 401 or 403, check the token and access permissions first. Even a 200 response may contain a login page or an unsupported list format. Ask the original source to confirm the response format, and don't submit the full URL to a third-party parsing site.

Two entries have the same name after an update. Which one should I choose?

First check whether an entry is in the subscription group you just updated, then open its details and compare the host, port and transport. If the other entry was imported individually earlier, this update won't change it. Confirm the new entry works before deciding whether to delete the old one.

Why can I edit the remark but not path or sni?

A remark helps identify an entry; path and sni are used for the connection. If the handshake fails after import, compare each field with the original configuration. Don't replace SNI with the domain in the remark or disable certificate verification for testing.

Get Shadowrocket

Get Shadowrocket for iPhone or iPad on the App Store for a one-time payment of $2.99. Check the App Store listing for system requirements. The Mac (Apple Silicon and Intel), Windows, Android and Linux versions are free; download the installer from this site. This site does not provide, sell or recommend servers or subscriptions.