TypeScript Type Definitions for Building Ads with DoubleClick Studio HTML5 SDK.

Enabler.d.ts

// Type definitions for building ads with DoubleClick Studio HTML5 SDK.
// Project: https://www.doubleclickbygoogle.com/solutions/digital-marketing/creative-solutions/
// Definitions by: Jarkko Syrjälä <https://github.com/jarkkosyrjala>
// SDK javascript documentation https://www.google.com/doubleclick/studio/docs/sdk/html5/en/namespace_studio.html

declare module studio {
    export class Enabler {
        constructor(useSingletonGetter:number);
        static getInstance():studio.Enabler;

        /**
         * Adds an event listener to the event target. The same handler can only be added once per the type. Even if you add the same handler multiple times using the same type then it will only be called once when the event is dispatched.
         * @param type
         * @param eventHandler
         * @param opt_capture
         * @param opt_handlerScope
         */
        addEventListener(type:string, eventHandler:Function, opt_capture?:boolean, opt_handlerScope?:any);
        /**
         * Adds a new handler for an otherwise unknown message.
         * @param messageName
         * @param handler
         */
        addMessageHandler(messageName:string, handler:Function);
        /**
         * Calls the callback when the enabler is initialized or after.
         * @param callback
         */
        callAfterInitialized(callback:Function);
        /**
         * Closes floating and popup creative types. If it is an expanding creative, close acts as a proxy to collapse.
         */
        close();
        /**
         * Closes the companion asset for floating, reminder, and pop-up creative types.
         */
        closeCompanion();
        /**
         * @deprecated Use requestCollapse() instead.
         */
        collapse();
        /**
         * Tracks a counter event.
         * @param eventId
         * @param opt_isCumulative
         */
        counter(eventId:string, opt_isCumulative?:boolean);
        /**
         * Triggers the display of the companion asset for floating, reminder, and pop-up advert types.
         */
        displayCompanion();
        /**
         * Opens a new window with the URL as identified by the given exit ID.
         * @param id The exit ID.
         * @param opt_url The url to navigate to.
         */
        exit(id:string, opt_url?:string);
        /**
         * Opens a new window with the URL as identified by the given exit ID. This differs from normal exit() as the url value will always override the value modified in Studio or elsewhere.
         * @param id The exit ID.
         * @param url The url to navigate to regardless of what has been set in Studio.
         */
        exitOverride(id:String, url:string);
        /**
         * Opens a new window with the URL as identified by the given exit ID with an optional queryString appended.
         * @param id
         * @param opt_queryString
         */
        exitQueryString(id:string, opt_queryString?:string);
        /**
         * Clips the container of the html asset from the expanded dimensions to the collapsed dimensions. Please use event listeners to invoke the collapsed state of the ad as the collapse event may be dispatched by the environment independently of calling studio.Enabler#requestCollapse().
         */
        finishCollapse();
        /**
         * Finalizes the expand call via the rendering code.
         */
        finishExpand();
        /**
         * Finishes fullscreen collapse.
         */
        finishFullscreenCollapse();
        /**
         * Finishes fullscreen expand.
         */
        finishFullscreenExpand();
        /**
         * Returns the current state of the container.
         */
        getContainerState():studio.sdk.ContainerState;
        /**
         * Returns the DART ad ID.
         * @return Integer value of the ID number (generated by DART) that identifies the ad.
         */
        getDartAdId():number;
        /**
         * Returns the DART asset ID.
         */
        getDartAssetId():string;
        /**
         * Returns the DART creative ID.
         */
        getDartCreativeId():number;
        /**
         * Returns the DART page ID.
         */
        getDartPageId():number;
        /**
         * Returns the DART rendering ID.
         */
        getDartRenderingId():string;
        /**
         * Returns the DART site ID.
         */
        getDartSiteId():number;
        /**
         * Returns the DART site name.
         */
        getDartSiteName():string;
        /**
         * Returns the expand direction.
         */
        getExpandDirection():studio.common.mde.Direction;
        /**
         * @deprecated Use getUrl(filename). Returns the runtime file name given the original compile-time file name. The original file name may have been mapped to a newer file name.
         */
        getFilename(originalFilename):string;
        /**
         * Returns an object representing the orientation of the device.
         */
        getOrientation():studio.common.Orientation;
        /**
         * Retrieves a creative parameter that the user can pass via queryString URL. This is also used internally to access ad configuration data.
         * @param variableName
         */
        getParameter(variableName:string):any;
        /**
         * Retrieves a creative parameter as an integer.
         * @param name
         */
        getParameterAsInteger(name:string):number;
        /**
         * Retrieves a creative parameter as a nullable string.
         * @param name
         */
        getParameterAsNullableString(name:string):string;
        getProfileId():number;
        /**
         * Gets the runtime URL given the original compile-time filename.
         * @param filepath The original full path of the asset
         */
        getUrl(filepath:string):string;
        /**
         * Returns the user's bandwidth according to DART bandwidth codes.
         */
        getUserBandwidth():number;
        /**
         * Returns the two-letter string representation of the user's country.
         */
        getUserCountry():string;
        /**
         * Returns the DART representation of the user's Nielsen Designated Market Area.
         */
        getUserDMACode():number;
        /**
         * Returns the two-letter string representation of the user's state or province.
         */
        getUserState():string;
        /**
         * Returns the user's zip code (for users in the United States, U.S. territories, and Canada).
         */
        getUserZipCode():string;
        /**
         * Checks if a user has interacted with the document.
         */
        hasUserInteracted():boolean;
        /**
         * Invoke a function in the parent container. This could be the top frame if served via a adj (script) tag, the serving iframe if served via and adi (iframe) tag.
         * @param functionName
         */
        invokeExternalJsFunction(functionName:string);
        /**
         * Invoke a function on the mraid api. This is different from invokeExternalJsFunction as you are given the results of the function in a callback.
         * @param methodName
         * @param opt_args
         * @param opt_callback
         */
        invokeMraidMethod(methodName:String, opt_args?:any[], opt_callback?:Function);
        /**
         * Returns whether the Enabler is intialized.
         */
        isInitialized():boolean;
        /**
         * Returns whether the parent page has loaded. The iframe is notified when the page has loaded and dispatches the StudioEvent.PAGE_LOADED event.
         */
        isPageLoaded():boolean;
        /**
         * Returns whether the ad is serving in the live environment or not.
         */
        isServingInLiveEnvironment():boolean;
        /**
         * Returns whether the ad is visible. The iframe is notified when the ad is visible and the enabler dispatches the StudioEvent.VISIBLE event.
         */
        isVisible():boolean;
        /** Loads an additional module. */
        loadModule(moduleName:string, opt_loadedCallback:Function);

        /** Loads an additional script file.*/
        loadScript(scriptUrl:string, opt_loadedCallback:Function);

        /**
         *  Initiates a query for the maximum allowable fullscreen dimensions. A studio.event.StudioEvent.FULLSCREEN_DIMENSIONS event will be dispatched with the maximum allowed width and height as properties. Some publishers may pad the fullscreen window for a lightbox-like experience. Because of this the maximum allowable dimensions may not take up the entire browser window or screen.
         */
        queryFullscreenDimensions();
        /**
         * Initiates a query to find out whether mock fullscreen expansion mode is supported. Please listen for the studio.event.StudioEvent.FULLSCREEN_SUPPORT event. This event will contain the support status.
         */
        queryFullscreenSupport();
        /**
         * Provide a method that allows the creative to define a chargeable event.
         * @example Enabler.registerChargeableEventName("SWIPE");
         */
        registerChargeableEventName(eventName:string);
        /**
         * Removes an event listener from the event target. The handler must be the same object as the one added. If the handler has not been added then nothing is done.
         */
        removeEventListener(type:string, eventHandler:Function, opt_capture?:boolean, opt_handlerScope?:any);
        /**
         * Removes a new handler for an otherwise unknown message.
         */
        removeMessageHandler(messageName:string);
        /**
         * @deprecated Use studio.Enabler#reportCustomVariableCount1(custom).
         */
        reportCustomClickVariable(postString:string);
        /**
         * @deprecated Use studio.Enabler#reportCustomVariableCount1(custom).
         */
        reportCustomImpressionVariable(postString:string);
        /**
         * Counts instances of the string parameter, aggregated as Custom Variable Count 1 in reports. The string must meet the following criteria:
         */
        reportCustomVariableCount1(customString:string);
        /**
         * Counts instances of the string parameter, aggregated as Custom Variable Count 2 in reports. The string must meet the following criteria:
         */
        reportCustomVariableCount2(customString:string);

        /**
         * Records a manual closing of a floating, pop-up, expanding, in-page with pop-up, or in-page with floating ad.
         */
        reportManualClose();
        /**
         * Initiates the collapse lifecycle. This begins by calling requestCollapse(), waiting for the COLLAPSE_START event, animating your collapse, then calling finishCollapse() when the creative has fully collapsed. Please use event listeners to invoke the collapsed state of the ad as the collapse event may be dispatched by the environment independently of calling studio.Enabler#requestCollapse().
         */
        requestCollapse();
        /**
         * Initiates the expand lifecycle. This begins by calling requestExpand(), waiting for the EXPAND_START event, animating your expand, then calling finishExpand() when the creative has fully expanded. Please use event listeners to invoke the expanded state of the ad as the expand may be dispatched by the environment independently of calling studio.Enabler#requestExpand(). This is especially true on networks such as the Google Display Network that display a hover timer before allowing the ad to expand. Typical usage will look like:
         */
        requestExpand();
        /**
         * Requests fullscreen collapse. Please listen for the studio.event.StudioEvent.FULLSCREEN_COLLAPSE_START event to start collapse.
         */
        requestFullscreenCollapse();
        /**
         * Requests fullscreen expand. If width and height are provided, expands to a rectangle of that width and height centered in the middle of the display (or browser window, if the browser is not fullscreen). Otherwise expands to the full size of the browser window/display. Note that on mobile devices the browser window typically takes up the entire display.
         * @param opt_width Width we would like to expand to in pixels.
         * @param opt_height Height we would like to expand to in pixels.
         */
        requestFullscreenExpand(opt_width:number, opt_height:number);


        /**
         * Set the dynamic content development values.
         * @param value The Dynamic Content development values.
         */
        setDevDynamicContent(value:any);
        /**
         * Sets the pixel offsets for the collapsed portion of the ad. This does not affect the local testing environment but when the ad is live the collapsed portion will be shown at 0x0. This method works by setting the marginLeft and marginTop of the body element which is set to relative positioning.
         * @param left
         * @param top
         * @param opt_expandedWidth
         * @param opt_expandedHeight
         * @param opt_startExpanded
         * @param opt_isMultiDirectional
         */
        setExpandingPixelOffsets(left:number, top:number, opt_expandedWidth?:number, opt_expandedHeight?:number, opt_startExpanded?:boolean, opt_isMultiDirectional?:boolean);
        /**
         * Prepopulates the width and height of a floating or peeldown creative.
         * @param width
         * @param height
         */
        setFloatingPixelDimensions(width:number, height:number);
        /**Adds a Hint to this creative
         * @param name
         * @param value
         */
        setHint(name:studio.sdk.hint.Hint, value:string):studio.Enabler;

        /**
         * Sets the isMultiDirectional flag.
         * @param isMultiDirectional
         */
        setIsMultiDirectional(isMultiDirectional:boolean);
        /**
         * Set the dynamic creative profile id.
         * @param value
         */
        setProfileId(value:number);
        /**
         * Sets the startExpanded flag, which controls whether the asset starts in the expanded state or not. If true, then when the initial requestExpand call will not be tracked or logged and will not trigger an expansion timer.
         * @param startExpanded
         */
        setStartExpanded(startExpanded:boolean);
        /**
         * Sets useCustomClose. This is primarily of use in mobile environments using MRAID. When this flag is set, it means that the creative will provide its own close button, so MRAID doesn't have to provide one.
         * @param useCustomClose
         */
        setUseCustomClose(useCustomClose:boolean);
        /**
         * Starts an event timer.
         * @param timerId
         */
        startTimer(timerId:string);
        /**Stops an event timer.*/
        stopTimer(timerId:string);
    }
}
// COMMON
declare module studio.common.Orientation {
    export enum Mode { LANDSCAPE, PORTRAIT }
}

declare module studio.common {
    export class Orientation {
        constructor(mode:studio.common.Orientation.Mode, opt_degree?:number);     //
        //TODO studio.common.Orientation
        /**
         * Returns the degrees of orientation. This is not dependable to calculate whether the device is landscape or portrait as the base orientation varies per device, per OS. This should be used to distinguish rotation for games and such.
         */
        getDegrees():number;
        /**
         * Returns the orientation mode of the device or browser.
         */
        getMode():studio.common.Orientation.Mode;
    }
}
declare module studio.common.mde {
    export class Direction {
        // TODO studio.common.mde.Direction =  "tl" || "tr" || "bl" || "br";
    }
}
// EVENTS
declare module studio.events {
    export class StudioEvent {
        constructor(type:string);
        addProperty(key:number, value:any):studio.events.StudioEvent;
        static COLLAPSE:string;
        static COLLAPSE_FINISH:string;
        static COLLAPSE_START:string;
        static EXIT:string;
        static EXPAND_FINISH:string;
        static EXPAND_START:string;
        static FULLSCREEN_COLLAPSE_FINISH:string;
        static FULLSCREEN_COLLAPSE_START:string;
        static FULLSCREEN_DIMENSIONS:string;
        static FULLSCREEN_EXPAND_FINISH:string;
        static FULLSCREEN_EXPAND_START:string;
        static FULLSCREEN_SUPPORT:string;
        static HIDDEN:string;
        static INIT:string;
        static INTERACTION:string;
        static ORIENTATION:string;
        static PAGE_LOADED:string;
        static VISIBLE:string;
    }
}
// studio.module package
declare module studio.module {
    /**
     * The available modules to load.
     */
    export class ModuleId {
        static ENABLER:string;
        static CONFIGURABLE:string;
        static CONFIGURABLE_FILLER:string;
        static VIDEO:string;
        static LAYOUTS:string;
        static FILLER:string;
        static RAD_VIDEO:string;
    }
}

// studio.sdk package
declare module studio.sdk {
    /**
     * Enum representing the container possible states.
     */
    export class ContainerState {
        static COLLAPSED:string;
        static COLLAPSING:string;
        static EXPANDED:string;
        static EXPANDING:string;
        static FS_COLLAPSING:string;
        static FS_EXPANDING:string;
        static FS_EXPANDED:string;
    }
    export class MraidMethod {
        static GET_CURRENT_POSITION:string;
        static GET_DEFAULT_POSITION:string;
        static GET_RESIZE_PROPERTIES:string;
        static GET_SCREEN_SIZE:string;
        static SET_RESIZE_PROPERTIES:string;
        static SIZE_CHANGE:string;
        static CREATE_CALENDAR_EVENT:string;
        static GET_MAX_SIZE:string;
        static PLAY_VIDEO:string;
        static STORE_PICTURE:string;
        static SUPPORTS:string;
    }
    export class logger {
        // TODO
    }


}
// TODO studio.sdk.configurable package

declare module studio.sdk.hint {
    export class Hint {
        // TODO
        //Enum of hints to be parsed on upload of a creative.
        static EXPANSION_MODE:string;
        static EXPANSION_TRIGGER:string;
    }
}

// TODO  studio.sdk.layouts package
// TODO  studio.sdk.rad package

declare module studio.utils {
    /**
     * Util for getting the initialized enabler reference by callback.
     */
    export class EnablerAccessor {
        constructor();
        /**
         * Invokes the given callback when the Enabler is initialized. The enabler is passed to the callback as the first argument.
         * @param enablerInitializedCallback The callback to call when the enabler has been initialized.
         */
        getInitializedEnablerByCallback(enablerInitializedCallback:Function); //function(studio.Enabler)
        /**
         * Waits until the enabler is initialized, then loads the given module. When the module is loaded, invokes the callback, if any was provided.
         * @param moduleId The module to load.
         * @param opt_callback The callback to invoke when the module is loaded.
         */
        loadModuleWhenReady(moduleId:studio.module.ModuleId, opt_callback?:Function);
    }
}

declare module studio.video {
    /**
     * Video reporting class to observe a video element.
     */
    export class Reporter {
        constructor(videoElement:HTMLVideoElement);
        // Static Methods
        /**
         * Observes a video element for reporting.
         * @param videoReportingIdentifier
         * @param videoElement
         * @param opt_trackAsAutoPlay
         */
        static attach(videoReportingIdentifier:string, videoElement:HTMLVideoElement, opt_trackAsAutoPlay?:boolean);

        /**
         * Stops a video reporting identifier from reporting.
         * @param videoReportingIdentifier
         */
        static detach(videoReportingIdentifier:string);
    }
}

/**
 * Enabler instance, an alias for studio.Enabler.getInstance()
 */
declare var Enabler:studio.Enabler;