VAST Integration for Malvertising Defense and Ad Quality

If you are an advertising platform, you can use HUMAN’s VAST integration to protect video ads against malicious behavior in Video Player Ad-Serving Interface Definition (VPAID) scripts and any subsequent scripts they load. This guide explains how to integrate and deploy HUMAN Malvertising Defense and Ad Quality with a VAST creative.

Configure macro values

Your platform must replace %creative-id% and other macros with actual values at serve time. HUMAN recommends and accepts the following fields: SeatID, DSP ID, SiteID, CreativeID, PublisherID and Referrer Domain. For details on each parameter, see Parameter Reference. If macros are not applicable or available for the seat (such as the member or buyer), Demand-Side Platform (DSP), site, publisher, or referrer domain, remove those query string parameters entirely.

Insert the HUMAN URL

To complete the integration and have complete protection, you must replace your original VAST URL with a HUMAN-wrapped URL. The HUMAN URL fetches the original VAST URL, unwraps it, and looks for a JavaScript VPAID resource to wrap and protect.

Ensure you add the query parameters for seat ID, DSP ID, and any other parameters that you are using in your existing Malvertising script integration.

The url parameter must contain the URL-encoded (encodeURIComponent in JavaScript) original VAST URL, and it must be the last query parameter in the HUMAN URL.

To integrate:

Encode the original VAST URL using encodeURIComponent or the equivalent function in your programming language.
Create the final HUMAN URL using the format below, replacing the placeholders with your real values.

Example HUMAN URL

https://vnhm.onevast.ac/v2/md/{YOUR-UNIQUE-DISTRIBUTION}?md-client-key={YOUR-UNIQUE-CLIENT-KEY}&md-creative-id={CREATIVE-ID}[&md-seat-id=...][&md-dsp-id=...][&md-site-id=...][&md-pub-id=...][&md-referrer-domain=...]&url={encoded-original-vast-url}

Use the new HUMAN URL instead of the original VAST URL wherever your ad server or DSP expects a VAST endpoint.

Below are examples of how to securely encode your original VAST URL component and generate the final HUMAN URL across different programming languages.

The examples below are for reference only. Do not use them in your production environment.

1 const originalVastUrl = 'https://example.com/vast.xml?param1=jane&param2=doe';
2 const encodedVastUrl = encodeURIComponent(originalVastUrl);
3 const resultVastUrl = `https://vnhm.onevast.ac/v2/md/{YOUR-UNIQUE-DISTRIBUTION}?md-client-key=${YOUR-UNIQUE-CLIENT-KEY}&md-creative-id=${CREATIVE-ID}&url=${encodedVastUrl}`;

Validate with HUMAN

Before using the HUMAN Malvertising Defense on live traffic, we recommend performing a series of integration tests. The HUMAN team will work directly with your platform team to ensure effectiveness.

You must provide a test page so our team can perform a full quality assurance pass.

Rollout across live domains

Phased rollout: Once validated, HUMAN recommends scaling the integration in phases. You can achieve this by deploying the solution on a specific number of websites or across a small percentage of traffic in your desired geographies. Once live on traffic, HUMAN will verify the results to ensure that incremental threats are detected and that the integration is functioning as expected.
Full rollout: After gaining confidence through the phased rollout, the integration can be deployed to your target traffic percentage (for example, 10 percent of traffic). HUMAN will continue to monitor the deployment. Incremental threats captured via the direct integration will be visible in the HUMAN Platform Feed dashboard.

Parameter Reference

HUMAN will generate your tag and enable your platform to pass additional data through custom fields. HUMAN will also provide the script distribution for {YOUR-UNIQUE-DISTRIBUTION}.

Providing additional fields outside of the creative ID will help HUMAN provide more insights into specific threats. HUMAN recommends and accepts the parameters listed in the table below.

Parameter	Is Required?	Description
url={ENCODED-ORIGINAL-VAST-URL}	Required	Original `encodeURIComponent`-encoded VAST URL
md-client-key={YOUR-UNIQUE-CLIENT-KEY}	Required	Your unique client key provided by HUMAN
md-creative-id={CREATIVE-ID}	Required	Creative ID of the ad being served
md-dsp-id={DSP-ID}	Recommended	DSP ID on the platform
md-seat-id={SEAT-ID}	Optional	Seat or Buyer ID on the DSP
md-site-id={SITE-ID}	Optional	Site ID on the platform
md-pub-id={PUB-ID}	Optional	ID of the Publisher
md-referrer-domain={REFERRER-DOMAIN}	Optional	Publisher domain where the ad is being served
md-customParameterName	Optional	You can pass any custom parameter by simply prepending “md-” to the parameter name (for example, `md-customParameterName`). Ensure to inform your HUMAN team when adding new parameters, and if you require this parameter to be passed in your Webhook responses.