M Ads Developer API

Integrate ads with one script and one function.

M Ads is designed to be deliberately small. Add the SDK once, then callMAds.show() whenever your app reaches a moment where an ad should appear.

Quickstart

Add the SDK to your page using the Site ID from the M Ads dashboard.

<script
  src="https://ads.mplace.cc/sdk.js"
  data-site="site_your_id_here">
</script>

Then trigger an ad:

await MAds.show();

MAds.show()

MAds.show() requests an eligible ad, renders it, waits for the user to finish the ad flow, and then resolves.

const result = await MAds.show({
  placement: "lesson-complete"
});

Option	Type	Required	Description
`placement`	string	No	A developer-defined label for where the ad appeared.

Placements

Placements are simple labels you choose. They help you understand where ads are being shown without identifying users.

await MAds.show({ placement: "quiz-complete" });
await MAds.show({ placement: "level-finished" });
await MAds.show({ placement: "download-ready" });

Keep placement names short and descriptive. They are used for aggregate analytics only.

Return values

The Promise resolves to an object describing whether an ad was shown.

{
  shown: true,
  adId: "ad_..."
}

If no ad is available, the SDK resolves without blocking the app:

{
  shown: false
}

Examples

Continue after an ad

async function handleContinue() {
  await MAds.show({ placement: "continue-button" });
  goToNextPage();
}

Save first, then show an ad

async function submitAssignment() {
  await saveAssignment();
  await MAds.show({ placement: "assignment-submitted" });
  showSuccessScreen();
}

React

async function handleNext() {
  await window.MAds.show({ placement: "lesson-complete" });
  setStep((step) => step + 1);
}

Ad formats

M Ads currently supports three creative types configured by the M Ads administrator:

Text + buttonHeadline, description and CTA.

Image + buttonVisual creative with a CTA.

MixedImage, text and CTA together.

The publisher integration does not need to change when the creative format changes.

Failure behavior

M Ads is fail-open by design. A network problem, unavailable ad, or temporary M Ads outage should never break the host app.

const result = await MAds.show();

// Continue regardless of whether an ad was available.
continueAppFlow();

The SDK may also return a reason such as missing_site_id or unavailable for debugging.

REST API

Most developers should use the JavaScript SDK. The public ad-serving endpoint used by the SDK is documented here for debugging and advanced integrations.

GET https://ads.mplace.cc/api/ad?site=SITE_ID&placement=PLACEMENT

Successful response:

{
  "ad": {
    "id": "ad_...",
    "format": "mixed",
    "headline": "Example",
    "description": "Example description",
    "imageUrl": "https://...",
    "destinationUrl": "https://example.com",
    "buttonLabel": "Learn more"
  },
  "placement": "lesson-complete"
}

A response with HTTP 204 means there is currently no eligible ad to serve.