Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mazeedplus.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This guide covers integrating Mazeed+ placement API into React Native mobile applications using WebView for rendering ad placements. Integration Method: Direct API call from mobile application

​
Mazeed+ Credentials

You will receive:
  • Publishable API Key – For x-publishable-api-key header
  • Placement ID – For identifier field

​
API Endpoint

POST https://api.mazeedplus.com/select-placement

​
Response Formats

​
JSON Response (Default)

When requesting with Accept: application/json (default):
AttributeTypeDescription
identifierStringThe placement ID requested
templateNameStringTemplate name
template_dataObjectStructured data for native rendering

​
HTML Response

When requesting with Accept: text/html, the API returns an HTML document directly in the response body.

​
Request Attributes

​
Required Attributes

AttributeDescriptionRequired
identifierPlacement ID provided by Mazeed+Yes
attributes.userIdUnique identifier for the userYes
attributes.mobileMobile number in international format (e.g., +9665xxxxxxx)Yes
AttributeDescriptionExample
attributes.countryCountry code"sa"
attributes.currencyCurrency code"sar"
attributes.firstnameUser’s first name"Ahmed"
attributes.lastnameUser’s last name"Al-Rashid"
attributes.genderUser’s gender"male" or "female"
attributes.ageUser’s age in years28
attributes.interestsArray of user interest strings["sports", "tech"]
attributes.confirmationrefOrder or transaction reference"ORD-12345"
attributes.paymenttypePayment method used"credit_card", "cash"
attributes.cartItemsJSON string of cart items"[{\"id\":\"123\"}]"
attributes.qSearch query for finding relevant products"كولومبي قهوه"

​
React Native Implementation

​
Configuration

// config/mazeed.ts
export const MAZEED_PUBLISHABLE_KEY = "pk_live_...";
export const MAZEED_PLACEMENT_ID = "checkout_success";

​
API Service

// api/mazeed.ts

import { MAZEED_PUBLISHABLE_KEY, MAZEED_PLACEMENT_ID } from "../config/mazeed";

export async function fetchMazeedPlacement(user: {
  userId: string;
  mobile: string;
  country?: string;
  currency?: string;
  firstname?: string;
  lastname?: string;
}) {
  const res = await fetch("https://api.mazeedplus.com/select-placement", {
    method: "POST",
    headers: {
      "x-publishable-api-key": MAZEED_PUBLISHABLE_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      identifier: MAZEED_PLACEMENT_ID,
      attributes: {
        userId: user.userId,
        mobile: user.mobile,
        country: user.country,
        currency: user.currency,
        firstname: user.firstname,
        lastname: user.lastname
      }
    })
  });

  if (!res.ok) {
    return { html: "", css: "" };
  }

  const data = await res.json();
  return {
    html: data.html as string | undefined,
    css: data.css as string | undefined
  };
}

​
WebView Renderer

​
Install Dependencies

npm install react-native-webview

​
WebView Component

// components/MazeedPlacementWebView.tsx

import React, { useMemo } from "react";
import { WebView } from "react-native-webview";

type Props = {
  html: string;  // Full HTML document from API
};

export const MazeedPlacementWebView: React.FC<Props> = ({ html }) => {
  if (!html) return null;

  return (
    <WebView
      originWhitelist={["*"]}
      source={{ html }}
    />
  );
};

​
Usage Example

// screens/PlacementScreen.tsx

import React, { useEffect, useState } from "react";
import { View, ActivityIndicator } from "react-native";
import { fetchMazeedPlacement } from "../api/mazeed";
import { MazeedPlacementWebView } from "../components/MazeedPlacementWebView";

export const PlacementScreen = () => {
  const [placement, setPlacement] = useState<{ html?: string; css?: string }>();

  useEffect(() => {
    (async () => {
      const result = await fetchMazeedPlacement({
        userId: "user_123",
        mobile: "+966512345678",
        country: "sa",
        currency: "sar"
      });

      setPlacement(result);
    })();
  }, []);

  if (!placement) return <ActivityIndicator />;

  if (!placement.html) return null;

  return (
    <View style={{ flex: 1 }}>
      <MazeedPlacementWebView html={placement.html} />
    </View>
  );
};

​
Integration Summary

Quick Checklist:
  • Get Publishable API Key and Placement ID from Mazeed+
  • Install react-native-webview
  • Configure credentials
  • Implement API service
  • Create WebView component
  • Integrate into screen
Data Flow:
  1. Call API with: identifier, userId, mobile
  2. Receive: html and css
  3. Render in WebView

​
Performance: Preloading WebView

Recommendation: Preload WebView before showing to users. 
// components/MazeedPlacementWebView.tsx (Enhanced)

import React, { useMemo, useState } from "react";
import { WebView } from "react-native-webview";
import { View, ActivityIndicator, StyleSheet } from "react-native";

type Props = {
  html: string;  // Full HTML document from API
};

export const MazeedPlacementWebView: React.FC<Props> = ({ html }) => {
  const [isLoaded, setIsLoaded] = useState(false);

  if (!html) return null;

  return (
    <View style={styles.container}>
      {!isLoaded && (
        <View style={styles.loaderContainer}>
          <ActivityIndicator size="large" color="#0000ff" />
        </View>
      )}
      <WebView
        originWhitelist={["*"]}
        source={{ html }}
        onLoadEnd={() => setIsLoaded(true)}
        style={[styles.webview, !isLoaded && styles.hidden]}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  loaderContainer: {
    ...StyleSheet.absoluteFillObject,
    justifyContent: "center",
    alignItems: "center",
    backgroundColor: "#ffffff",
  },
  webview: {
    flex: 1,
  },
  hidden: {
    opacity: 0,
  },
});

​
Best Practices

  • Hide WebView until content is fully rendered
  • Use onLoadEnd callback
  • Don’t show empty WebView while loading

​
Mobile Number Format

Correct Format: 
mobile: "+966512345678"
Incorrect Format: 
mobile: "0512345678"  // Missing country code