Integration Guide

This comprehensive guide walks you through integrating PocketDNS into your platform step by step.

Overview

PocketDNS integration involves three main steps:

1. Create User Sessions - Generate login URLs for your users
2. Embed the Interface - Display our domain interface in your app
3. Handle Domain Purchases - Manage domains and DNS after purchase

Step 1: Create User Sessions

To launch our embedded domain interface, first create a user session:

const createUserSession = async (userIdentifier: string, email?: string) => {
  const response = await fetch('https://api.pocketdns.com/api/v1/users', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      user_identifier: userIdentifier, // Your internal user ID
      email: email // Optional but recommended
    })
  });

  if (!response.ok) {
    throw new Error(`Failed to create session: ${response.statusText}`);
  }

  const { user_identifier, login_url } = await response.json();
  return { user_identifier, login_url };
};

Session Details

• User Identifier: Your unique internal user ID
• Email: Optional but recommended for better user experience
• Login URL: Valid for 24 hours, used to embed the interface
• Session: Automatically handles authentication for the embedded interface

Step 2: Embed the Domain Interface

Use the login_url from step 1 to embed our domain interface:

React SDK

Install the React SDK: npm install @pocketdns/react-sdk

import {
  PocketDNS,
  PocketDNSProps,
  DomainRegistrationData
} from '@pocketdns/react-sdk';


const DomainsPage = () => {
  const handleRegistraation = (data: DomainRegistrationData) => {
    console.log(data.domain, data.registrant_name);
  }

  const config = {
    apiKey: process.env.REACT_APP_DOMAINS
  }
}

Basic HTML Embed

<iframe 
  src="{login_url}"
  width="100%"
  height="600px"
  frameborder="0"
  allow="payment"
  title="PocketDNS Domain Interface">
</iframe>

Responsive Embed

.domain-embed {
  position: relative;
  width: 100%;
  height: 600px;
  min-height: 500px;
}

.domain-embed iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  border: none;
  border-radius: 8px;
}

@media (max-width: 768px) {
  .domain-embed {
    height: 500px;
  }
}

<div class="domain-embed">
  <iframe 
    src="{login_url}"
    allow="payment"
    title="PocketDNS Domain Interface">
  </iframe>
</div>

Step 3: Handle Domain Purchases

After a successful domain purchase, you can manage the domains programmatically.

Get User's Domains

const getUserDomains = async (userIdentifier: string) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/users/${userIdentifier}/domains`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to fetch domains: ${response.statusText}`);
  }

  const { domains } = await response.json();
  return domains;
};

Get Domain Details

const getDomainDetails = async (domainId: string) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to fetch domain: ${response.statusText}`);
  }

  return await response.json();
};

Complete Integration Example

Here's a complete integration example that demonstrates all the steps:

class PocketDNSIntegration {
  private apiKey: string;
  private baseUrl: string;

  constructor(apiKey: string, environment: 'production' | 'sandbox' = 'production') {
    this.apiKey = apiKey;
    this.baseUrl = environment === 'production' 
      ? 'https://api.pocketdns.com'
      : 'https://api.sandbox.pocketdns.com';
  }

  async createUserSession(userIdentifier: string, email?: string) {
    const response = await fetch(`${this.baseUrl}/api/v1/users`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        user_identifier: userIdentifier,
        email
      })
    });

    if (!response.ok) {
      throw new Error(`Failed to create session: ${response.statusText}`);
    }

    return await response.json();
  }

  async getUserDomains(userIdentifier: string) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/users/${userIdentifier}/domains`,
      {
        headers: {
          'Authorization': `Bearer ${this.apiKey}`
        }
      }
    );

    if (!response.ok) {
      throw new Error(`Failed to fetch domains: ${response.statusText}`);
    }

    const { domains } = await response.json();
    return domains;
  }

  async getDomainDetails(domainId: string) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/domains/${domainId}`,
      {
        headers: {
          'Authorization': `Bearer ${this.apiKey}`
        }
      }
    );

    if (!response.ok) {
      throw new Error(`Failed to fetch domain: ${response.statusText}`);
    }

    return await response.json();
  }
}

// Usage
const pocketDNS = new PocketDNSIntegration('your-api-key', 'sandbox');

// Create session and embed
const session = await pocketDNS.createUserSession('user-123', 'user@example.com');
// Use session.login_url in your iframe

// Later, fetch user's domains
const domains = await pocketDNS.getUserDomains('user-123');
console.log('User domains:', domains);

Integration Checklist

Use this checklist to ensure your integration is complete:

• [ ] API Key Setup: Generated and securely stored API keys
• [ ] Environment Configuration: Using correct URLs for sandbox/production
• [ ] User Session Creation: Successfully creating user sessions
• [ ] Iframe Integration: Domain interface loads correctly
• [ ] Domain Retrieval: Can fetch user's domains after purchase
• [ ] Error Handling: Proper error handling for all API calls
• [ ] Security: API keys never exposed client-side
• [ ] Testing: Tested complete flow in sandbox environment

Next Steps

Once your basic integration is working:

1. Explore Frontend Integration for React components and advanced patterns
2. Set up DNS Management to automatically configure domains
3. Review Best Practices for production deployment
4. Check the API Reference for advanced features

TIP

Start with sandbox environment and thoroughly test your integration before switching to production!