feat: Improve Apify Proxy Usage docs (#935)

Every now and then, we have a free user that can't use Apify Proxy from
inside of the Actors because they're trying to connect to
`proxy.apify.com`, not internally through `$APIFY_PROXY_HOSTNAME`, which
fails since it's considered an external connection, which is banned on
the Free plan.

This improves the Apify Proxy connection instructions to hopefully
better explain that when connecting to Apify Proxy from inside an Actor,
they should either use the helpers in the `Actor` class in the SDK, or
use the `APIFY_PROXY_HOSTNAME`, `APIFY_PROXY_PORT` and
`APIFY_PROXY_PASSWORD` environment variables.

Closes #740

---------

Co-authored-by: Michał Olender <[email protected]>

Author: fnesveda

sources/platform/proxy/usage.md

@@ -13,23 +13,60 @@ slug: /proxy/usage
 
 ## Connection settings
 
-To connect to the Apify Proxy, you use the [HTTP proxy protocol](https://en.wikipedia.org/wiki/Proxy_server#Web_proxy_servers). This means that you need to configure your HTTP client to use the proxy server at `proxy.apify.com:8000` and provide it with your Apify Proxy password and the other parameters described below.
+To connect to Apify Proxy, you use the [HTTP proxy protocol](https://en.wikipedia.org/wiki/Proxy_server#Web_proxy_servers). This means that you need to configure your HTTP client to use the proxy server at the Apify Proxy hostname and provide it with your Apify Proxy password and the other parameters described below.
 
 The full connection string has the following format:
 
 ```text
-http://<username>:<password>@proxy.apify.com:8000
+http://<username>:<password>@<hostname>:<port>
 ```
 
+:::caution
+All usage of Apify Proxy with your password is charged towards your account. Do not share the password with untrusted parties or use it from insecure networks, as **the password is sent unencrypted** due to the HTTP protocol's [limitations](https://www.guru99.com/difference-http-vs-https.html).
+:::
+
+### External connection
+
+If you want to connect to Apify Proxy from outside of the Apify Platform, you need to have a paid Apify plan (to prevent abuse).
+If you need to test Apify Proxy before you subscribe, please [contact our support](https://apify.com/contact).
+
 | Parameter           | Value / explanation |
 |---------------------|---------------------|
-| Proxy type          | `HTTP`              |
 | Hostname            | `proxy.apify.com`, alternatively you can use static IP addresses `18.208.102.16`, `35.171.134.41`. |
 | Port                | `8000`              |
 | Username            | Specifies the proxy parameters such as groups, [session](#sessions) and location. See [username parameters](#username-parameters) below for details. <br/>**Note**: this is not your Apify username.|
-| Password            | Proxy password. Your password is displayed on the [Proxy](https://console.apify.com/proxy/groups) page in Apify Console. In Apify [Actors](../actors/index.mdx), it is passed as the `APIFY_PROXY_PASSWORD`  environment variable. See the [environment variables docs](../actors/development/programming_interface/environment_variables.md) for more details. |
+| Password            | Apify Proxy password. Your password is displayed on the [Proxy](https://console.apify.com/proxy/groups) page in Apify Console. <br/>**Note**: this is not your Apify account password. |
+
+:::caution
+If you use these connection parameters for connecting to Apify Proxy from your Actors running on the Apify Platform, the connection will still be considered external, it will not work on the Free plan, and on paid plans you will be charged for external data transfer. Please use the connection parameters from the [Connection from Actors](#connection-from-actors) section when using Apify Proxy from Actors.
+:::
+
+Example connection string for external connections:
+
+```text
+http://auto:[email protected]:8000
+```
+
+### Connection from Actors
+
+If you want to connect to Apify Proxy from Actors running on the Apify Platform, the recommended way is to use built-in proxy configuration tools in the [Apify SDK JavaScript](/sdk/js/docs/guides/proxy-management) or [Apify SDK Python](/sdk/python/docs/concepts/proxy-management)
+
+If you don't want to use these helpers, and want to connect to Apify Proxy manually, you can find the right configuration values in [environment variables](../actors/development/programming_interface/environment_variables.md) provided to the Actor.
+By using this configuration, you ensure that you connect to Apify Proxy directly through the Apify infrastructure, bypassing any external connection via the Internet, thereby improving the connection speed, and ensuring you don't pay for external data transfer.
+
+| Parameter           | Source / explanation |
+|---------------------|---------------------|
+| Hostname            | `APIFY_PROXY_HOSTNAME` environment variable  |
+| Port                | `APIFY_PROXY_PORT` environment variable      |
+| Username            | Specifies the proxy parameters such as groups, [session](#sessions) and location. See [username parameters](#username-parameters) below for details. <br/>**Note**: this is not your Apify username.|
+| Password            | `APIFY_PROXY_PASSWORD` environment variable |
 
-> **WARNING:** All usage of Apify Proxy with your password is charged towards your account. Do not share the password with untrusted parties or use it from insecure networks – **the password is sent unencrypted** due to the HTTP protocol's [limitations](https://www.guru99.com/difference-http-vs-https.html).
+Example connection string creation:
+
+```js
+const { APIFY_PROXY_HOSTNAME, APIFY_PROXY_PORT, APIFY_PROXY_PASSWORD } = process.env;
+const connectionString = `http://auto:${APIFY_PROXY_PASSWORD}@${APIFY_PROXY_HOSTNAME}:${APIFY_PROXY_PORT}`;
+```
 
 ### Username parameters
 
@@ -67,7 +104,7 @@ The table below describes the available parameters.
         <td>Optional</td>
         <td>
             <p>If specified to <code>session-new_job_123</code>, for example, all proxied requests with the same session identifier are routed through the same IP address. If not specified, each proxied request is assigned a randomly picked least used IP address.</p>
-            <p>The session string can only contain numbers (0-9), letters (a-z or A-Z), dot (.), underscore (_), a tilde (~). The maximum length is 50 characters.</p>
+            <p>The session string can only contain numbers (0–9), letters (a-z or A-Z), dot (.), underscore (_), a tilde (~). The maximum length is 50 characters.</p>
             <p>Session management may work differently for residential and SERP proxies. Check relevant documentations for more details.</p>
         </td>
     </tr>
@@ -103,8 +140,8 @@ Web scrapers can rotate the IP addresses they use to access websites. They assig
 
 Depending on whether you use a [browser](https://apify.com/apify/web-scraper) or [HTTP requests](https://apify.com/apify/cheerio-scraper) for your scraping jobs, IP address rotation works differently.
 
-* Browser – a different IP address is used for each browser.
-* HTTP request – a different IP address is used for each request.
+* Browser—a different IP address is used for each browser.
+* HTTP request—a different IP address is used for each request.
 
 Use [sessions](#sessions) to controll how you rotate and [persist](#session-persistence) IP addresses. See our guide [Anti-scraping techniques](/academy/anti-scraping/techniques) to learn more about IP address rotation and our findings on how blocking works.
 
@@ -134,12 +171,12 @@ To test that your requests are proxied and IP addresses are being [rotated](/aca
 
 ### A different approach to `502 Bad Gateway`
 
-There are times when the `502` status code is not comprehensive enough. Therefore, we have modified our server with `590-599` codes instead to provide more insight:
+Sometimes when the `502` status code is not comprehensive enough. Therefore, we have modified our server with `590-599` codes instead to provide more insight:
 
 * `590 Non Successful`: upstream responded with non-200 status code.
 * `591 RESERVED`: *this status code is reserved for further use.*
-* `592 Status Code Out Of Range`: upstream responded with status code different than 100-999.
-* `593 Not Found`: DNS lookup failed - [`EAI_NODATA`](https://github.com/libuv/libuv/blob/cdbba74d7a756587a696fb3545051f9a525b85ac/include/uv.h#L82) or [`EAI_NONAME`](https://github.com/libuv/libuv/blob/cdbba74d7a756587a696fb3545051f9a525b85ac/include/uv.h#L83).
+* `592 Status Code Out Of Range`: upstream responded with status code different than 100–999.
+* `593 Not Found`: DNS lookup failed, indicating either [`EAI_NODATA`](https://github.com/libuv/libuv/blob/cdbba74d7a756587a696fb3545051f9a525b85ac/include/uv.h#L82) or [`EAI_NONAME`](https://github.com/libuv/libuv/blob/cdbba74d7a756587a696fb3545051f9a525b85ac/include/uv.h#L83).
 * `594 Connection Refused`: upstream refused connection.
 * `595 Connection Reset`: connection reset due to loss of connection or timeout.
 * `596 Broken Pipe`: trying to write on a closed socket.