Skip to content

Commit c91050d

Browse files
authored
docs: Add section about adblockers in JS documentation (#1151)
1 parent fc2bff0 commit c91050d

File tree

1 file changed

+48
-0
lines changed
  • src/collections/_documentation/platforms/javascript

1 file changed

+48
-0
lines changed

src/collections/_documentation/platforms/javascript/index.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,54 @@ Then, you can see the error in your dashboard:
6060

6161
[{% asset js-index/error-message.png alt="Error in Unresolved Issues with title This is my fake error message" %}]({% asset js-index/error-message.png @path %})
6262

63+
{% capture __alert_content -%}
64+
When you are using our CDN, it may happen, that some people will use ad-blocking or script-blocking extensions. When this happens, our SDK won't be fetched and initialized properly. Because of this, any call to SDKs API will fail and may cause your application to misbehave. If this could apply to your use-case, read the section below on how to mitigate this issue.
65+
{%- endcapture -%}
66+
{%- include components/alert.html
67+
title="Dealing with Ad-Blockers"
68+
content=__alert_content
69+
level="warning"
70+
%}
71+
72+
The best way to deal with script-blocking extensions is to use the SDK package directly through the `npm` and bundle it with your application.
73+
This way, you can be sure, that the code will be always there as you expect it to be.
74+
75+
The second way is to download the SDK from our CDN and host it yourself, this way SDK will still be separated from the rest of your code, but you'll be certain that it won't be blocked, as it's origin will be the same as the origin of your website.
76+
77+
You can easily fetch it using `curl` or any other similar tool:
78+
79+
```sh
80+
$ curl https://browser.sentry-cdn.com/{% sdk_version sentry.javascript.browser %}/bundle.min.js -o sentry.browser.{% sdk_version sentry.javascript.browser %}.min.js -s
81+
```
82+
83+
The last option, is to use `Proxy` guard, that will make sure that your code won't break, even when you will call our SDK which was blocked.
84+
`Proxy` is supported by all browser except Internet Explorer, however there are no extensions in these browsers anyway. Also if `Proxy` is not in any of your user's browser, it will be silently skipped, so you don't have to worry about it breaking anything.
85+
86+
The snippet should be placed just **above** the `<script>` tag containing our CDN bundle.
87+
88+
The snippet in a readable format presents like this:
89+
90+
```js
91+
if ("Proxy" in window) {
92+
var handler = {
93+
get: function(_, key) {
94+
return new Proxy(function(cb) {
95+
if (key === "flush" || key === "close") return Promise.resolve();
96+
if (typeof cb === "function") return cb(window.Sentry);
97+
return window.Sentry;
98+
}, handler);
99+
}
100+
};
101+
window.Sentry = new Proxy({}, handler);
102+
}
103+
```
104+
105+
And here is more useful, minified snippet, that you can copy-paste directly:
106+
107+
```html
108+
<script>if("Proxy"in window){var n={get:function(o,e){return new Proxy(function(n){return"flush"===e||"close"===e?Promise.resolve():"function"==typeof n?n(window.Sentry):window.Sentry},n)}};window.Sentry=new Proxy({},n)}</script>
109+
```
110+
63111
## Capturing Errors
64112
Automatically and manually capture errors, exceptions, and rejections.
65113

0 commit comments

Comments
 (0)