SDK

The SDK is a tool that gives the integrating partner the possibility to hook in and steer the Welect flow. It is a flexible approach that could be used in any web context. This quick introduction gives an overview of the important stages.

Integration

The SDK is an optimized JavaScript bundle. A Welect manager will provide you a link to this bundle. SDK bundles are configured individually for each partner or placement. But no worries - in any case the SDK bundle is ready to use and does not need any configuration from the SDK consumer side.

Example:

<!-- Embedded into the HTML of the serving site -->
<script src="https://static.welect.de/p/bundles/<a-bundle-id>.js#wbss"></script>

or

// Dynamic loaded
var script = document.createElement('script');
script.type = 'text/javascript';
script.src = 'https://static.welect.de/p/bundles/<a-bundle-id>.js#wbss';
document.head.appendChild(script);

Preflight Checks

There are two things that could be checked in advance:

1. Has the user already completed a session and is this session still valid? (*)
2. Is any advertisement available that could be shown to the user?

The first point can be answered by using the checkToken method of the Welect object that will be provided via the SDK. And the second point can be checked with the checkAvailability method. Both methods accept callbacks that will be called either in the success or failure case.

The availability check (checkAvailability) can be called many times but it must be called at least once before continuing the Welect process.

(*It is possible do define the duration in which the user does not need to watch an ad again. For example 15 minutes)

Run Welect's Ad Chooser

The ad chooser executes the Welect process for selecting and playing an advertisement. This process can be triggered via the runSession method. It will take care of everything that belongs to this process. An alternative way is to use the startURL method. It returns an URL as a string. By opening this URL in any way in a browser window (tab or iframe) it will trigger the same flow.

Post Ad Checks

After running Welect's Ad Chooser a token will be returned. The token could be avaiable either as query paramater or as a cookie. The query parameter is used in combination with a redirect and will be append to redirect URL. The name of the parameter can be defined by Welect. The below specified checkToken method can analyze the token for validity.

API reference

Methods of welect|Welect objects:

interface CheckAvailabilityConfig {
    onAvailable: () => void;
    onUnavailable: () => void;
}

interface RunSessionConfig {
    onSuccess: () => void;
    onAbort: () => void;
}

interface CheckTokenConfig {
    onValid: () => void;
    onInvalid: () => void;
}

interface Welect {
    /**
     * Checks if any ads are available.
     */
    checkAvailability?: (config: CheckAvailabilityConfig) => void;

    /**
     * Initiates the Welect overlway with its ad chooser.
     */
    runSession?: (config: RunSessionConfig) => void;

    /**
     * Analyzes the current window if a complete session is present.
     * A user has completed a session when the ad has been viewed till the end.
     */
    checkToken?: (config: CheckTokenConfig) => void;

    /**
     * Returns an URL which represents the Welect overlay with its ad
     * chooser.
     */
    startURL?: () => string;
}

(Hint: To create the config objects use plain old JavaScript objects.)

Example

// Just a dummy method for this example!
const logFn = (event) => {
    return () => { console.log(event) };
};

// Has the user already watched a Welect ad?
Welect.checkToken({
    // Yes
    onValid: logFn('watched ad completely'),
    // No
    onInvalid: () => {
        // Are there any ads to show?
        Welect.checkAvailability({
            // No
            onUnavailable: logFn('no ad available'),
            // Yes
            onAvailable: () => {
                // Play the Welect dialog
                Welect.runSession({
                    // Was the process interrupted by something?
                    onAbort: logFn('view was cancelled'),
                    // Ad view was completely
                    onSuccess: () => {
                        // Let`s check the token again
                        Welect.checkToken({
                            // Everything is fine
                            onValid: logFn('watched ad completely'),
                            // Please contact us in this case
                            onInvalid: logFn('something went wrong'),
                        })
                    },
                });
            },
        });
    },
});