First Analysis
This first guide is going to help you to run your first Analysis.
If you're not familiar with GraphQL, please have a look at its dedicated section in this documentation.
In order to analyse your first content, you'll have to send a request to our API. This request is going to launch the AdSecure's crawler on the content of your choice.
Prerequisites
Before starting this guide, please be sure that you're ready to use our service by following the steps illustrated in the Quickstart section.
Simple case
For the purpose of this first example, we're going to analyse a simple web page:
https://examples.adsecure.com/simple
In order to ask the AdSecure's crawler to analyse this content, we need to create a new Analysis
entry. When you create a new Analysis
, the AdSecure's crawler is informed that a new task needs to be handled and start analysing the provided content.
The entry's creation in GraphQL is associated to a mutation
query and because we want to analyse the content of https://examples.adsecure.com/simple
, we're going to put this URL as the value of the input.content
parameter.
Also, and in order to be able to retrieve our analysis later in this guide, we're going to ask the GraphQL API to return us the Analysis
's id
.
Query
mutation {
createAnalysis(input: {
content: "https://examples.adsecure.com/simple"
}) {
id
}
}
Response
{
"data": {
"createAnalysis": {
"id": "YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI="
}
}
}
Congrats! You've just created your first analysis. It was pretty simple but it one of the most important queries that you'll have to make against our API.
From that point, a new Analysis
entry has been created in our database and the AdSecure crawler is now analysing the https://examples.adsecure.com/simple
web page.
As the analysis is going to be complete after a few seconds, let's prepare our next query in order to fetch its result.
By using the id
returned in the response body, we can retrieve the Analysis
's entry that we've just created. We're also asking the GraphQL API to return us some extra information accessible in this document such as the Analysis
's Status
or the listing of the violations that the crawler could have identified.
As retrieving an entry in GraphQL is associated to a simple query
, the following payload should be used:
Query
query {
analysis(id: "YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI=") {
id
content
status
violation
violations
}
}
Response
{
"data": {
"analysis": {
"id": "YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI=",
"content": "https://examples.adsecure.com/simple",
"status": "DONE",
"violation": false,
"violations": []
}
}
}
The response's body returns a result that mirrors the shape of the requested query. Let's review them one by one:
id
: This field is theAnalysis
's identifier. Unique, it's the one that we got in the response's body of our first query.content
: The content that we asked the AdSecure's crawler to analyse.status
: TheAnalysis
'sStatus
. This field has its value set asDONE
which mean that the analysis was already completed at the time of your query. If you try to get theAnalysis
before its full completion you might see this field set asINITIAL
. In the same way if an error happens, it will be reflected here by usingERROR
as value.violation
: If set totrue
, theviolation
field report that the crawler identified one or more violations. In our example, this field's value isfalse
, meaning that the AdSecure's crawler didn't found any violation on thehttps://examples.adsecure.com/simple
web page.violations
: This field lists the violations found during an analysis. As mentioned previously, no violations were found during the analysis and so this array is empty.
Positive case
Let's now make a new analysis, but this time on a content that we know is going to contain some violations. In this next example, we're going to analyse a web content that is positive for the Landing Page Error detection:
https://examples.adsecure.com/404
We're here going to use the same query as the one used previously but updating the input.content
field with this new content URL.
Query
mutation {
createAnalysis(input: {
content: "https://examples.adsecure.com/404"
}) {
id
}
}
Response
{
"data": {
"createAnalysis": {
"id": "YW5hbHlzaXN8YThiYzI0M2ItNTY3ZS13ZjA5LWIwOWItMTI1YmMzNGMxMzRyfDIwMTgtMDktMDI="
}
}
}
Our new analysis is now created and we can retrieve it by using the same query as in our first example but replacing the previous id
by the one generated for this new Analysis
:
Query
query {
analysis(id: "YW5hbHlzaXN8YThiYzI0M2ItNTY3ZS13ZjA5LWIwOWItMTI1YmMzNGMxMzRyfDIwMTgtMDktMDI=") {
id
content
status
violation
violations
}
}
Response
{
"data": {
"analysis": {
"id": "YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI=",
"content": "https://examples.adsecure.com/404",
"status": "DONE",
"violation": true,
"violations": ["landing-page-error"]
}
}
}
As you can see here, the field violation
is now set to true
meaning that at least one violations was found by the crawler. In order to have more information about it we need to check the field violations
. Here we see that the array is now containing the landing-page-error
value which is the identifier of the Landing Page Error detection.
Having a detection's identifier listed in this violations
array means that the AdSecure crawler found some positive results for the corresponding detection during its analysis.
Next steps
These examples were illustrating some simple use cases of our service. As your own usage could require more advanced features, we're inviting you to keep on discovering our API through the others guides available: