Cloudsurf-browseragent

Cloudsurf is een browseragent die wordt beheerd door Shopify. Deze voert webbrowsers uit in de cloud, zodat AI-agents en tools van Shopify webpagina's kunnen bezoeken en hiermee kunnen communiceren op de manier waarop een mens dat doet. Dit type browsen staat bekend als agentic browsing.

Cloudsurf bezoekt alleen een pagina wanneer een Shopify-tool hier opdracht toe geeft. De tool gaat niet zelfstandig het web crawlen of indexeren. Je ziet mogelijk Cloudsurf-verkeer in je webshop, of op een openbare website, wanneer een Shopify-tool browst voor een merchant of een klant.

Cloudsurf-verzoeken kunnen een Web Bot Auth-handtekening en een Shopify-useragent bevatten, oftewel de tekst in een verzoek die de software identificeert die deze heeft verzonden. Je kunt deze gegevens gebruiken om Cloudsurf-verkeer in je logboeken en botbeheertools te herkennen.

Cloudsurf-usecases

Shopify-tools gebruiken Cloudsurf om webpagina's te bezoeken voor de volgende doeleinden:

  • AI-agents: Sidekick en andere Shopify AI-agents browsen op webpagina's om taken te voltooien waarom een merchant of een klant heeft verzocht.
  • Testen en kwaliteitscontroles: Shopify-tools laden webpagina's om ze te testen, schermafbeeldingen te maken en te controleren op weergaveproblemen.

Cloudsurf-verkeer in webshops

Cloudsurf-bezoeken aan je webshop kunnen afkomstig zijn van Shopify-tools die je gebruikt, van Shopify AI-agents die browsen voor klanten, of van intern testen en onderzoek dat wordt uitgevoerd met Shopify-tools. Lees meer informatie over Botactiviteit in je webshop identificeren.

Web Bot Auth-handtekeningen

Shopify-tools die Cloudsurf gebruiken, kunnen hun verzoeken ondertekenen met Web Bot Auth, dat HTTP-berichthandtekeningen gebruikt. Een geldige handtekening bewijst dat Shopify een verzoek heeft geautoriseerd. Iedereen kan een useragent kopiëren, dus een handtekening is de meest betrouwbare manier om Cloudsurf-verkeer te identificeren.

Niet elk Cloudsurf-verzoek is ondertekend, omdat ondertekening afzonderlijk wordt ingeschakeld voor elke Shopify-tool. Als een verzoek beweert van Cloudsurf te zijn maar geen geldige handtekening heeft, dan kun je niet verifiëren of het van Shopify afkomstig is.

Ondertekende Cloudsurf-verzoeken gebruiken de Signature-Agent-waarde "https://cloudsurf.shopify.io". Cloudsurf ondertekent elk verzoek voor de Shopify-tool die deze gebruikt, en elke handtekening verloopt 60 seconden nadat deze is aangemaakt. Cloudsurf publiceert zijn openbare sleutels in een sleutel-directory op https://cloudsurf.shopify.io/.well-known/http-message-signatures-directory.

Ondertekende verzoeken bevatten de volgende HTTP-headers:

Web Bot Auth-headers die zijn opgenomen in ondertekende Cloudsurf-verzoeken, met de waarde of indeling van elke header
HeaderWaarde
Signature-Agent"https://cloudsurf.shopify.io"
Signature-InputDe handtekeningparameters, waaronder het sleutel-ID, het ed25519-algoritme, de aanmaak- en vervaltijden en de web-bot-auth-tag.
HandtekeningDe Ed25519-handtekening van het verzoek.

Het volgende voorbeeld illustreert de indeling van de headers die Cloudsurf toevoegt:

Signature-Agent: "https://cloudsurf.shopify.io"
Signature-Input: sig1=("@authority" "signature-agent");created=<timestamp>;keyid="<key ID>";alg="ed25519";expires=<timestamp>;nonce="<nonce>";tag="web-bot-auth"
Signature: sig1=:<signature>:

De parameter keyid in elke handtekening is de JSON Web Key (JWK)-vingerafdruk van de sleutel waarmee deze is ondertekend.

Een botbeheerservice die Web Bot Auth ondersteunt, kan een verzoek verifiëren. De service haalt de sleutels op uit de sleutel-directory en zoekt de sleutel die overeenkomt met de parameter keyid. Vervolgens worden de handtekening en de vervaltijd ervan gecontroleerd. Als je een botbeheerservice gebruikt, raadpleeg dan de bijbehorende documentatie om te lezen hoe je geverifieerde bots toestaat.

Cloudsurf-useragents

Standaard voegt Cloudsurf de tekst Shopify/Cloudsurf (bot; +https://www.shopify.com) toe aan het einde van de standaard useragent van de browser. Sommige Shopify-tools vervangen de gehele useragent door hun eigen useragent.

Bekijk de volgende tabel voor voorbeelden van useragents in Cloudsurf-verkeer:

Useragents die kunnen worden meegegeven met Cloudsurf-verkeer, vermeld per Shopify-tool of -modus die deze verzendt
BronUseragentGegevens
Cloudsurf<browser-useragent> Shopify/Cloudsurf (bot; +https://www.shopify.com)De standaard useragent. Het begin van de tekenreeks is de standaard useragent van de browser die de sessie uitvoert, dus deze verandert afhankelijk van de browser en de versie ervan.
Emulatie van mobiel apparaatEen standaard iPhone- of Android-useragentTools die testen hoe een pagina wordt weergegeven op een telefoon, verzenden de useragent van die telefoon, zonder de Cloudsurf-tekst. Als een van deze verzoeken is ondertekend, dan kun je dit verifiëren met Web Bot Auth.

Useragents kunnen veranderen wanneer Shopify-tools worden geüpdatet. Om Cloudsurf-verkeer op een betrouwbare manier te identificeren, verifieer je de Web Bot Auth-handtekening ervan in plaats van alleen overeenkomsten te zoeken in de useragent.