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 the Analysis'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: The Analysis's Status. This field has its value set as DONE which mean that the analysis was already completed at the time of your query. If you try to get the Analysis before its full completion you might see this field set as INITIAL. In the same way if an error happens, it will be reflected here by using ERROR as value.

  • violation: If set to true, the violation field report that the crawler identified one or more violations. In our example, this field's value is false, meaning that the AdSecure's crawler didn't found any violation on the https://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:

← ConceptsSelect a specific Location →