⚙️ SDK Methods Reference

This document provides detailed information about all available methods in the Magfi Ad Network SDK.

Core Methods

getInstance(appCode)

Initializes and returns an instance of the Magfi Ad Network SDK.

Parameters

Name	Type	Description
APP_CODE	string	Your unique application code provided by Magfi

Returns

Type	Description
Object	The Magfi SDK instance

Example

const magfi = window.MagfiAdNetwork.getInstance("YOUR_APP_CODE");

add(options)

Creates and initializes an ad instance.

Parameters

Name	Type	Description
options	Object	Configuration options
options.code	string	The unique ad placement code

Returns

Type	Description
AdInstance	An instance of the ad

Example

// Basic usage
const ad = magfi.add({ AD_CODE: "AD_CODE" });

Ad Instance Methods

These methods are available on the ad instance returned by the add() method.

show(callbacks)

Displays the ad.

Parameters

Name	Type	Description
callbacks	Object	(Optional) Callback functions
callbacks.onClosed	Function	Called when the ad is closed
callbacks.onGranted	Function	Called when permissions are granted
callbacks.onSkip	Function	Called when ad is skipped

Returns

Type	Description
void	No return value

Example

ad.show({
  onClosed: () => {
    console.log("Ad was closed");
    // Reward the user or continue app flow
  },
  onGranted: () => {
    console.log("Permission granted");
  },
  onSkip: ()=>{
    console.log("Ad was skipped");
  }
});

isReady()

Checks if the ad is ready to be displayed.

Returns

Type	Description
boolean	true if the ad is ready to be shown, otherwise false

Example

if (ad.isReady()) {
  ad.show();
} else {
  console.log("Ad not ready yet");
}

addEventListener(eventName, callback)

Adds an event listener to the ad instance.

Parameters

Name	Type	Description
eventName	string	The name of the event to listen for
callback	Function	The function to execute when the event occurs

Returns

Type	Description
void	No return value

Example

ad.addEventListener("onReady", () => {
  console.log("Ad is ready to be shown");
  showAdButton.disabled = false;
});

ad.addEventListener("onError", () => {
  console.log("Ad failed to load");
});

removeEventListener(eventName, callback)

Removes an event listener from the ad instance.

Parameters

Name	Type	Description
eventName	string	The name of the event
callback	Function	The function that was originally passed to addEventListener

Returns

Type	Description
void	No return value

Example

const onReadyHandler = () => {
  console.log("Ad is ready");
};

// Add the event listener
ad.addEventListener("onReady", onReadyHandler);

// Later, remove the event listener
ad.removeEventListener("onReady", onReadyHandler);

Events

These events can be used with the addEventListener method.

Event Name	Description
onReady	Triggered when the ad is loaded and ready to be displayed
onGranted	Triggered when the user grants the necessary permissions
onStart	Triggered when the ad starts playing
onClose	Triggered when the ad is closed
onError	Triggered when an error occurs during ad loading or display
adNotFound	Triggered when no ad is available for the requested placement
onSkip	Triggered when the user skips the rewarded ad without receiving the reward

TypeScript Definitions

If you're using TypeScript, here are the type definitions for the SDK:

interface AdCallbacks {
  onClosed?: () => void;
  onGranted?: () => void;
  onSkip?: () => void;
}

type AdEventName = "onReady" | "onGranted" | "onStart" | "onClose" | "onError" | "adNotFound" | "onSkip";

interface AdInstance {
  show: (callbacks?: AdCallbacks) => void;
  isReady: () => boolean;
  addEventListener: (eventName: AdEventName, callback: () => void) => void;
  removeEventListener: (eventName: AdEventName, callback: () => void) => void;
}

interface AdOptions {
  AD_CODE string;
}

interface MagfiAdNetwork {
  getInstance: (appCode: string) => {
    add: (options: AdOptions) => AdInstance;
  };
}

declare global {
  interface Window {
    MagfiAdNetwork: MagfiAdNetwork;
  }
}

Error Handling

It's important to properly handle errors when working with ads. Here are some common error scenarios and how to handle them:

Ad Not Ready

Always check if the ad is ready before showing it:

if (ad.isReady()) {
  ad.show();
} else {
  console.log("Ad not ready yet");
  // Show a loading indicator or alternative content
}

Ad Load Error

Listen for the onError event to detect when an ad fails to load:

ad.addEventListener("onError", () => {
  console.log("Ad failed to load");
  // Update UI to reflect error state
  // Hide ad button or show alternative content
});

No Ad Available

Listen for the adNotFound event to detect when no ad is available:

ad.addEventListener("adNotFound", () => {
  console.log("No ad available");
  // Hide ad-related UI elements
  // Show alternative content
});