How to Import ss:// and vmess:// Links into Shadowrocket: Share Links vs. Subscription URLs

Learn how ss://, vmess://, vless://, and trojan:// share links are structured, how they differ from subscription URLs, and how importing and updates work. All examples are fictitious.

At a glance

If you already have a link from a service provider, first determine whether it represents a single server entry or a subscription URL used to fetch a list. An imported server entry won’t update automatically when the provider changes its configuration; a subscription retains its source URL so you can fetch the list again. This guide uses Home and Add Server on iPhone and iPad to explain how to import each type, confirm an update, and identify what to check if you can’t connect afterward.

First, identify the type of link

Share links beginning with ss://, vmess://, vless://, or trojan:// usually contain the parameters for one server entry. If a web page lists ten links like these, they’re still ten separate entries. Importing them one by one won’t turn them into a subscription group that can be refreshed.

A URL starting with https:// only indicates that it uses HTTPS; it doesn’t mean it’s a subscription. A provider’s login page, information page, or subscription endpoint could all use HTTPS. Enter an address in the URL field under Subscribe only if the provider identifies it as subscription-compatible and Shadowrocket can recognize the response.

4 types
Share link prefixes covered in this guide: ss://, vmess://, vless://, trojan://
1 entry
Each share link shown here corresponds to one server entry
1 URL
A subscription entry retains its source URL and requests that address again when refreshed

How to read the parameters in four share link formats

The domains, port combinations, and credentials below are for illustration only and cannot be used to connect. 8388 and 443 are example ports used here, not ports required by these protocols. When importing a link, copy the provider’s original text as-is; don’t add or remove parameters based on these examples.

  • Shadowsocks (ss://): In a common format, the user information section before @ contains the encryption method and password, while the server address and port follow @. The user information may be Base64URL-encoded. If the link includes a plugin parameter, keep it and its value intact. Don’t treat the entire section before @ as the password.
  • VMess (vmess://): A common share format places a Base64-encoded JSON object after the prefix, so the address may not be visible in the original text. After decoding, add is the server address, port is the port, id is the UUID, and net specifies the transport. If net is ws, also check the WebSocket path and the host specified by the provider. host doesn’t necessarily match add.
  • VLESS (vless://): A common URI places the UUID before @. The type and security values after the question mark specify the transport and security layer, respectively. encryption=none can appear alongside security=tls: it doesn’t mean TLS is disabled and isn’t a reason to change TLS settings.
  • Trojan (trojan://): A common URI places the password before @, followed by the server address and port. If it includes sni, that value is the server name used for the TLS handshake. Don’t change it to match the connection address just because the two values differ.
ss://[email protected]:8388#Demo-SS
vmess://DEMO_BASE64_PAYLOAD
vless://[email protected]:443?encryption=none&type=tcp&security=tls&sni=vl.example.com#Demo-VLESS
trojan://[email protected]:443?sni=tr.example.com#Demo-Trojan
https://example.com/sub?token=xxxx

Import a single entry or add a subscription from Home

For a complete share link, import it directly to avoid mistyping transport or TLS fields. Select a protocol type manually only when you already have the individual parameters. When Type is set to Subscribe, the value you enter is the source of a server list, not the address of a single server.

Type:Subscribe

Recommended

If you have a compatible subscription and need to refresh its list, save the complete source address in URL.

Best for: keeping a provider-maintained server list up to date through a subscription

Type:Shadowsocks

Create a Shadowsocks entry manually by entering the address, port, encryption method, and password supplied by the provider. Check the relevant parameters if a plugin is required.

Best for: when you have individual parameters for a single Shadowsocks server

How to tell: consider what needs updating after you save

To update a manually added entry, edit it or import a new link. To sync an entire provider-maintained list, refresh the corresponding subscription group. Editing one entry in a subscription group isn’t the same as updating the subscription.

  1. Import a single share link: Copy the complete ss://, vmess://, or other link, then open Shadowrocket. If a clipboard import prompt appears, make sure it contains the link you just copied, then allow Shadowrocket to paste and import it. If you have a QR code for the same link, you can also scan it from Home. If the link isn’t recognized and the provider has supplied individual parameters, go to Home → + → Add Server, choose the appropriate Type, and enter them manually.
  2. Add a subscription URL: Go to Home → + → Add Server, set Type to Subscribe, paste the complete address into URL, and save. Don’t paste only the domain or remove parameters after ?. Return to Home and check that the subscription group lists server entries, not just that the group name appears.
  3. Check what’s selected: On Home, select the entry you just imported or updated, then connect if needed. Successfully adding an entry doesn’t mean it’s selected. Seeing a server name only confirms that the entry is in the app; it doesn’t mean the server is currently reachable.

How to verify a subscription refresh

Refreshing a subscription requests the saved URL again and attempts to parse the returned list. Seeing the old list doesn’t prove the new request succeeded. Even if the refresh completes without an error, the entries may be unchanged because the provider returned the same list.

What to do when a provider changes its settings

If you originally imported a share link
  • Get a new share link and import it, or edit the existing entry using the provider’s updated parameters.
  • If the old and new entries have the same name, compare the actual address, port, and transport. Confirm that the new entry is selected on Home before removing the old one.
If you originally added a subscription
  • If the source address hasn’t changed, select the relevant subscription group on Home and tap Update. If the address has changed, edit the subscription’s URL first.
  • Check the entries the provider explicitly says have changed. If the entry you had selected was removed, select the one you actually want to use on Home.

To verify an update, check a known change. For example, if the provider announced a port change for a particular entry, open that entry after refreshing and verify its port instead of just counting the entries.

Troubleshooting failed imports, empty subscriptions, and connection issues

Why didn’t importing an ss:// link add an entry?

First, make sure you copied the entire single-line link, from ss:// to the end, without including explanatory text, quotation marks, or line breaks. If the source page shows only truncated text, use the provider’s copy option to get the original. Don’t try to fill in a missing encoded section yourself.

Why is the subscription group empty after saving?

Compare the URL with the one provided and check whether you used a login page by mistake, left out query parameters, or selected the wrong subscription format. Even an HTTP 200 response may contain a login page or error message rather than a server list. If the app shows HTTP 401 or 403, first check the credentials and access permissions for the subscription URL you’re using.

The subscription refresh timed out, but existing entries still work. Is that normal?

The subscription endpoint and the servers in its list are separate destinations. Working existing entries don’t mean the subscription endpoint is reachable. Try refreshing the same group again on your current network, and compare results over Wi-Fi and cellular if needed. If only the refresh fails, check the subscription URL and request path first; there’s no need to reimport entries that still work.

An entry appears in the list, but websites won’t load after I select it. What should I check first?

First, check the current selection and connection status on Home, then check Global Routing. In Direct mode, website results don’t tell you whether the selected proxy works. In Config mode, rules determine how traffic is routed. Once you’ve confirmed that the request is going through the selected server, check the entry’s port, transport, and TLS settings. Don’t disable certificate verification to work around a name or certificate mismatch.

Download Shadowrocket for free