Google Ads Developer Blog

Ending support for VAST 1 and F2F in the IMA SDK

Posted: 11 Apr 2014 01:29 PM PDT

On May 5, 2014, in the spirit of spring cleaning, the IMA Flash SDK will be dropping support for several rarely-used formats and SDKs:

VAST 1 XML format. The IMA Flash SDK will continue to support VAST 2 and will continue to improve on its existing beta support for VAST 3. For more information about what versions of VAST, VPAID and VMAP the IMA Flash SDK supports, visit the Video Features and SDK Compatibility page.

Flash-in-Flash (F2F) creatives. VPAID, the industry standard for interactive video ads, is the recommended alternative for replacing F2F creatives. The IMA Flash SDK currently supports VPAID 1 and has beta support for VPAID 2.

IMA Flash SDK v1. This version of the SDK will no longer be guaranteed to work and won't receive bug fixes, updates, or responses to support issues. V3 of the IMA Flash SDK will be the only fully supported version of the SDK.

Dart Shell SDK. This DoubleClick SDK will no longer be guaranteed to work and won't receive bug fixes, updates, or responses to support issues.

What will happen if VAST 1 or an F2F creative is sent to the SDK?

If a VAST 1 ad tag response or F2F creative is sent to the SDK, the SDK will raise an AdErrorEvent with an appropriate error. For example, a VAST 1.0 response will return an AdErrorCodes.VAST_PARSING_ERROR which can be handled with the following ActionScript modified from the Flash IMA SDK example app:

  // ...
  import com.google.ads.ima.api.AdErrorCodes;

  private function initAdsLoader():void {
    // ...
    adsLoader.addEventListener(AdErrorEvent.AD_ERROR, adsLoadErrorHandler);
  }

  private function adsLoadErrorHandler(event:AdErrorEvent):void {
    // ...
    if (event.error.errorCode == AdErrorCodes.VAST_PARSING_ERROR) {
      trace("Invalid VAST format."); 
      // Error handling logic...
    }
  }

Retrieving entities

When retrieving entities, you may have run into errors such as ServerError, QuotaError, or client library specific errors like RemoteException. Generally these errors are not caused by user error, but caused by the API server being busy, or by issues with the entities you are retrieving being too large or corrupted. If you're already following our best practices of paging through your entities with our suggested page size and are still running into these errors from time-to-time, you can tackle these issues by writing code to handle the exceptions.

The general way we recommend you reduce the page size, wait a few seconds, and then retry the request to handle most errors you can receive. If it continues to fail, repeat this process up to five times. This will give you an idea of whether the failure is a temporary server error, or if there is a deeper issue. The following is an example that augments the GetAllLineItemsExample from the Google Ads API Java Client Library showing how to do this. It reduces the page size for each retry by halving it, and starts off the wait time between retries at two seconds, doubling it with each retry.

  private static final int MAX_RETRY_LIMIT = 5;
  private static final long BASE_WAIT_TIME = 2000;

  public static void runExample(DfpServices dfpServices, DfpSession session)
      throws Exception {
    int pageLimit = StatementBuilder.SUGGESTED_PAGE_LIMIT;

    // Get the LineItemService.
    LineItemServiceInterface lineItemService =
        dfpServices.get(session, LineItemServiceInterface.class);
    // Create a statement to select all line items.
    StatementBuilder statementBuilder =
        new StatementBuilder().orderBy("id ASC").limit(pageLimit).offset(0);

    // Default for total result set size.
    int totalResultSetSize = 0, retryCount = 0;
    LineItemPage page = null;
    long waitTime = BASE_WAIT_TIME;

    do {
      // Reset these values for each page.
      retryCount = 0;
      pageLimit = StatementBuilder.SUGGESTED_PAGE_LIMIT;
      waitTime = BASE_WAIT_TIME;
      page = null;

      do {
        try {
          System.out.printf(
              "Getting line items with page size of %d at offset %d (attempt " +
                  "%d)...\n", pageLimit,
              statementBuilder.getOffset(), retryCount + 1);
          // Get line items by statement.
          page = lineItemService.getLineItemsByStatement(
              statementBuilder.toStatement());
          System.out.printf("Attempt %d succeeded.\n\n", retryCount + 1);
        } catch (Exception e) {
          pageLimit /= 2;
          System.out.printf(
              "Attempt %d failed. Retrying in %d milliseconds with page size " +
                  "of %d...\n",
              retryCount + 1, waitTime, pageLimit);
          Thread.sleep(waitTime);
          waitTime *= 2;
          statementBuilder.limit(pageLimit);
          retryCount++;
        }
      } while (page == null && retryCount < MAX_RETRY_LIMIT);

      if (page != null) {
        totalResultSetSize = page.getTotalResultSetSize();
        // Your code to handle the line item page, e.g., save it to a database.
      } else {
        throw new Exception(String.format(
            "Failed to get line items at offset %s with page size %d after " +
                "%d attempts.",
            statementBuilder.getOffset(), pageLimit, retryCount));
      }

      statementBuilder.increaseOffsetBy(pageLimit);
    } while (statementBuilder.getOffset() < totalResultSetSize);

    System.out.printf("Number of results found: %d\n", totalResultSetSize);
  }

Using the above code, the output would look like the following if the first three attempts failed, but the fourth one succeeded for the first page.

Getting line items with page size of 500 at offset 0 (attempt 1)...
  Attempt 1 failed. Retrying in 2000 milliseconds with page size of 250...
  Getting line items with page size of 250 at offset 0 (attempt 2)...
  Attempt 2 failed. Retrying in 4000 milliseconds with page size of 125...
  Getting line items with page size of 125 at offset 0 (attempt 3)...
  Attempt 3 failed. Retrying in 8000 milliseconds with page size of 62...
  Getting line items with page size of 62 at offset 0 (attempt 4)...
  Attempt 4 succeeded.

  Getting line items with page size of 500 at offset 62 (attempt 1)...
  Attempt 1 succeeded.

If you're getting exceptions that weren't addressed by our examples and are unclear on how to diagnose them, then you can always write to us on the API forums. Include the requestId of the call that failed, especially in the case that you receive a SERVER_ERROR.

- Vincent Tsao, DFP API Team

Saturday, April 12, 2014