AdPlatform-Server/MetaApi/GATEWAY_INTEGRATION.md

Gateway Integration: Meta & TikTok Provider Routing

Overview

The Gateway's ExecutionService already routes provider="google" to the GoogleApi container. Adding Meta and TikTok follows the same pattern.

---

1. Gateway ExecutionService Changes

GetProviderUrl() — add meta + tiktok routing

private string GetProviderUrl(string provider)
{
    return provider.ToLower() switch
    {
        "google" => Environment.GetEnvironmentVariable("GOOGLE_PROVIDER_URL")
                     ?? _config["Providers:Google:Url"]
                     ?? "http://localhost:5200",

        "meta"   => Environment.GetEnvironmentVariable("META_PROVIDER_URL")
                     ?? _config["Providers:Meta:Url"]
                     ?? "http://localhost:5300",

        "tiktok" => Environment.GetEnvironmentVariable("TIKTOK_PROVIDER_URL")
                     ?? _config["Providers:TikTok:Url"]
                     ?? "http://localhost:5400",

        _ => throw new ArgumentException($"Unknown provider: {provider}")
    };
}

GetProviderKey() — add meta + tiktok internal keys

private string GetProviderKey(string provider)
{
    return provider.ToLower() switch
    {
        "google" => Environment.GetEnvironmentVariable("GOOGLE_INTERNAL_KEY")
                     ?? _config["Providers:Google:InternalKey"] ?? "",

        "meta"   => Environment.GetEnvironmentVariable("META_INTERNAL_KEY")
                     ?? _config["Providers:Meta:InternalKey"] ?? "",

        "tiktok" => Environment.GetEnvironmentVariable("TIKTOK_INTERNAL_KEY")
                     ?? _config["Providers:TikTok:InternalKey"] ?? "",

        _ => ""
    };
}

---

2. Gateway Environment Variables (Azure Container Apps)

Add to the Gateway container's env vars:

# Meta
META_PROVIDER_URL=https://usim-adp-metaapi.internal.<env>.azurecontainerapps.io
META_INTERNAL_KEY=<shared-secret>

# TikTok
TIKTOK_PROVIDER_URL=https://usim-adp-tiktokapi.internal.<env>.azurecontainerapps.io
TIKTOK_INTERNAL_KEY=<shared-secret>

---

3. Gateway appsettings.json — MultiChannel StatusMappings

The Gateway already has a MultiChannel config section for status mapping. Add/verify meta and tiktok entries:

{
  "MultiChannel": {
    "google": {
      "StatusMappings": {
        "ENABLED": "active",
        "PAUSED": "paused",
        "REMOVED": "cancelled"
      }
    },
    "meta": {
      "StatusMappings": {
        "ACTIVE": "active",
        "PAUSED": "paused",
        "DELETED": "cancelled",
        "ARCHIVED": "archived"
      }
    },
    "tiktok": {
      "StatusMappings": {
        "ENABLE": "active",
        "DISABLE": "paused",
        "DELETE": "cancelled"
      }
    }
  }
}

---

4. Account Validation (Optional — implement when ready)

Currently ValidateGoogleAccountAsync checks Google-specific account setup. When ready, add equivalent methods:

// In ExecutionService or a dedicated AccountValidationService:
private async Task ValidateMetaAccountAsync(string adAccountId) { ... }
private async Task ValidateTikTokAccountAsync(string advertiserId) { ... }

These would verify the external account ID exists and is accessible before forwarding operations to the provider containers.

---

5. Database Views & Stored Procedures

Meta

-- vwMetaAccount: mirrors vwGoogleAccount for accNetwork='meta'
CREATE VIEW vwMetaAccount AS
SELECT accId, accClientId, accExternalAccountId, accLoginAccountId, ...
FROM tbAdAccount WHERE accNetwork = 'meta';

-- spMetaAccount: account linking/validation
-- spMetaCredential: token storage (System User token doesn't expire, but store for reference)

TikTok

-- vwTikTokAccount: mirrors vwGoogleAccount for accNetwork='tiktok'
CREATE VIEW vwTikTokAccount AS
SELECT accId, accClientId, accExternalAccountId, accLoginAccountId, ...
FROM tbAdAccount WHERE accNetwork = 'tiktok';

-- spTikTokAccount: account linking/validation
-- spTikTokCredential: access token storage (doesn't expire unless revoked)

---

6. Port Map (All Services)

Service	Port	Container Name
Gateway	5000	usim-adp-gateway
Creative	5100	usim-adp-creative
GoogleApi	5200	usim-adp-googleapi
MetaApi	5300	usim-adp-metaapi
TikTokApi	5400	usim-adp-tiktokapi
Management	5500	usim-adp-management

---

7. Testing Checklist

For each new provider (meta, tiktok):

• Container builds and starts locally
• GET / returns service info
• GET /internal/health returns ok
• POST /internal/execute with Ping operation works (no auth needed for Ping)
• POST /internal/execute rejects without X-Internal-Key
• POST /internal/execute with CreateCampaign returns emulated response
• Gateway routes provider="meta" / provider="tiktok" correctly
• Gateway passes X-Internal-Key header
• End-to-end: client app → Gateway → provider container → emulated response
• Swagger UI accessible at /swagger