Affiliate Documentation — How to Use VektraPulse

Welcome! These docs are organized in the order you'll actually use them: set up tracking, get conversions back, then tune profit, automation, and scale. Most readers can be live in under 10 minutes.

Quick Start Guide (5–7 minutes)

Follow these steps once. After that, most days are just: create link → buy traffic → watch profit and alerts.

1. Create an offer and landing (or connect your existing funnel URLs).
2. Create a campaign and generate a tracking link. Use this link in your ad platform or network—not the raw landing URL.
3. Paste the postback URL from VektraPulse into your affiliate network so conversions register with the correct click_id.
4. Add cost (manual CSV/import or cost sync where available) so the Profit dashboard shows real ROAS—not click vanity.
5. Turn on Telegram alerts for the metrics you care about (spend spikes, CR drops, rule triggers).
6. Optional: Meta CAPI, TikTok Events API & GA4 so postbacks also feed ad platforms (Affiliate workspaces only).

In the app · Dashboard overview after your first campaign and a few test clicks.

Creating campaigns and tracking links

Offers, landings, and sources

Organize traffic the way media buyers think: offer (what you promote), landing (where the user lands), source (Facebook, push network, UTM, etc.). Campaigns tie these together and produce a single tracking URL per combination you want to measure.

What the tracking URL does

A hit on the tracking endpoint records the click (with geo, device, referrer where available), attaches a unique click_id, then 302-redirects the user to your landing or offer URL. Always use HTTPS links in production ads where possible.

GET https://<your-domain>/api/v1/track/{campaign_id}
→ 302 Redirect → https://your-lander.example/...

In the app · Campaign editor: offer, landing, source tags, and the generated tracking URL.

Postback Center & conversion flow setup

Postbacks are server-to-server conversion calls from your affiliate network (or your own backend) into VektraPulse. They close the loop: click → conversion → profit and CAPI fan-out.

Endpoint

VektraPulse accepts GET and POST on the same path (query parameters).

GET https://<your-domain>/api/v1/postback?click_id={click_id}&payout=10.50&currency=USD&status=approved

# Optional: pass your network's transaction id
GET ...&tx_id=NETWORK_TX_123

• click_id — required; must match the id from the click (macros from the network).
• payout — revenue for this conversion (optional but recommended for P&L).
• currency — defaults to USD if omitted.
• status — e.g. approved (network-specific mapping may apply).

In the app · Affiliate network: global postback URL field with VektraPulse macros filled in.

Rules engine & traffic routing

Rules let you react automatically when conditions match: pause a source, route to a different landing, fire webhooks, or flag traffic for review—without waiting for a manual refresh.

Example conditions (illustrative)

Example actions

• Pause campaign / source — stop buying immediately.
• Webhook — notify your Slack, n8n, or in-house optimizer.
• Route traffic — A/B landings or backup offer paths (where supported in your plan).

In the app · Rules builder: condition group, match mode (ALL/ANY), and ordered actions.

GEO Balancer — route traffic by country

GEO Balancer runs at click time — before the offer redirect. Route US traffic to one landing, send reviewers to a white page, block datacenter GEOs, or run country-level split tests without a separate redirect hop.

1. Open GEO Balancer from the sidebar and create a named balancer (e.g. "US-EU split").
2. Add country or region rules: route to a landing, block, send to white page, or split-test variants.
3. In the campaign editor, attach the balancer. Clicks now pass through GEO logic before redirect.
4. Use the built-in test tool to simulate a click from a specific country before going live.

• Works alongside the Visual Rules Engine — GEO runs first at redirect, rules handle post-click automation.
• White pages live under White Pages in the sidebar; link them from GEO rules for compliance flows.
• View per-country stats on the campaign analytics geo map.

Real-time Profit Dashboard & cost sync

Profit is only as honest as your cost inputs. Sync ad spend (platform reports, CSV, or integrations) so ROAS and net P&L match reality—not “clicks only.”

Automatic ad spend sync

Connect Meta Ads, TikTok Ads, or Google Ads under Settings → Ad Platforms. OAuth tokens are encrypted per workspace. Spend syncs every 30 minutes (or on demand) and rolls into the Profit Dashboard for true ROI and ROAS.

1. Connect each ad platform via OAuth — no manual CSV uploads required for daily spend.
2. Map platform campaigns to VektraPulse campaigns (auto-match or manual mapping table).
3. Synced spend appears alongside network revenue in the Profit Dashboard — fix mapping before trusting ROAS.

• Align time zones with your ad accounts when comparing days.
• Reconcile currency if you buy in multiple tenders.
• Use tags / sources consistently so cost rolls up to the same dimensions as clicks.

In the app · Profit view: revenue from postbacks vs. spend, by campaign and source.

AI Campaign Optimizer — how to use it

The optimizer reads your recent performance (clicks, conversions, spend where available) and proposes concrete next steps: scale winners, cut losers, adjust bids or creatives. Treat it as a copilot: you stay responsible for policy, brand, and network compliance.

1. Open the optimizer from the campaign or global AI entry point in the app.
2. Select the time window (e.g. last 7 days) and scope (campaign / source).
3. Review suggestions; apply changes in-platform or manually in the ad network.
4. Re-check after 24–48h—models work best with stable tracking and clean postbacks.

Telegram alerts setup

Connect a Telegram bot or chat as documented in-app, then subscribe to alert rules: threshold breaches, rule triggers, or digest summaries. Keep notification volume actionable—alert fatigue kills reaction speed.

1. Create a bot token (BotFather) or use the workspace onboarding flow if provided.
2. Authorize the chat where alerts should land.
3. Map alert types to severity (info vs. critical).
4. Test with a manual trigger or a sandbox campaign.

In the app · Alerts: connected Telegram chat and sample alert templates.

Meta CAPI, TikTok Events API & Google Conversion API (GA4)

For Affiliate workspaces, VektraPulse can forward conversions from postbacks to ad platforms via server-to-server APIs—better signal when browser pixels miss events (iOS, ad blockers, short sessions).

Where to connect

In the app: Integrations — configure Meta CAPI, TikTok Events API, and Google (GA4 Measurement Protocol). Use test events before going live.

Marketing overview: CAPI integrations

REST endpoints (authenticated, Affiliate only)

Base path: /api/v1/integrations/...

GET    /api/v1/integrations/summary
GET    /api/v1/integrations/meta-capi
PUT    /api/v1/integrations/meta-capi
DELETE /api/v1/integrations/meta-capi
POST   /api/v1/integrations/meta-capi/test

GET    /api/v1/integrations/tiktok-events
PUT    /api/v1/integrations/tiktok-events
DELETE /api/v1/integrations/tiktok-events
POST   /api/v1/integrations/tiktok-events/test

GET    /api/v1/integrations/google-conversion
PUT    /api/v1/integrations/google-conversion
DELETE /api/v1/integrations/google-conversion
POST   /api/v1/integrations/google-conversion/test

In the app · Integrations page: Meta pixel/CAPI token fields, test event panel, connection status.

Fraud protection & traffic quality

Fraud and quality modules highlight suspicious patterns (velocity, IP/datacenter clusters, impossible device mixes, etc.). Use scores as signals—combine with your own review and network feedback before hard-blocking large sources.

Traffic Quality Score

Each click gets a 0–100 score combining bot signals, IP reputation, datacenter origin, behavior fingerprints and velocity. Use it to spot bad sources fast and as a condition in your Rules.

• Pair fraud signals with rules to auto-pause or route.
• Compare quality across sources and landings, not global averages only.
• Build a 'Quality > 70' rule to auto-pause sources whose average TQS drops below your bar.

Smart Traffic Protection (Advanced Traffic Protection)

Smart Traffic Protection combines multi-layer detection and explainable AI scoring to route suspicious visitors to safe pages while preserving real-user conversion flow. It is designed to reduce false positives compared with classic one-signal cloaking.

1. Enable protection per campaign and set a risk threshold (0-100).
2. Configure signal weights (IP/ASN, user-agent, referrer, fingerprint, behavior) based on your traffic profile.
3. Review Cloak Logs daily: inspect reasons, label rows (moderator vs real user), and let self-learning improve future verdicts.

• Use multiple White Page variants for safer moderation handling and lower pattern repeatability.
• Use the simulator tab before going live to preview score outcomes for representative traffic scenarios.
• Guardrail recommendation: raise threshold if too many real users are routed to white, lower threshold if moderator leakage is still visible.

Account security, API keys & login protection

Workspace owners and admins manage security under Settings → Account Security. The dashboard shows a live security score and recent auth events.

Two-factor authentication (2FA)

Enable TOTP (authenticator app) or Telegram-based 2FA. Backup codes are generated once — store them offline. Workspace owners can require 2FA for all members.

1. Settings → Account Security → enable TOTP or link Telegram for one-tap codes.
2. Save backup codes when prompted. They are shown only once.
3. On login, enter your password first; if 2FA is enabled, complete the second step with your app or Telegram code.

API keys (scoped automation)

Create keys under Settings → API Keys. Keys use vp_live_ or vp_test_ prefixes, optional expiry, and granular scopes (campaigns, conversions, reports, etc.). Secrets are shown once at creation.

• Assign minimum scopes — a read-only reporting key should not have write access.
• Revoke compromised keys immediately; usage and last IP are logged.
• Never commit keys to git — use environment variables in your automation.

# API keys use scoped prefixes — store the secret once at creation
Authorization: Bearer vp_live_xxxxxxxxxxxxxxxx

# Example: list campaigns (requires campaigns:read scope)
GET /api/v1/campaigns

Password policy & recovery

Passwords are checked against known breach databases (HIBP) at registration and login. Reuse of recent passwords is blocked. Use Forgot password on the login page to reset via email link (expires in 1 hour).

Team & multi-user access

Invite teammates with appropriate roles (viewer, buyer, admin—exact roles depend on your plan). Share campaigns and dashboards without sharing personal ad account passwords; access is enforced per workspace.

In the app · Team settings: invite flow and role assignment.

Referral program

Earn stackable bonus subscription days by inviting other teams. Your unique link (VP-XXXXXXXX) lives under Settings → Referral Program.

1. Copy your referral link or use the pre-filled share buttons for Telegram and X.
2. When someone registers via your link and completes their first payment, you receive 30 bonus days; they receive 14 bonus days.
3. Track pending and completed referrals, total days earned, and remaining balance on the same page.
4. Bonus days extend access after a paid plan ends. Self-referrals are ignored; each referred workspace counts once.

Advanced features

Custom events

Map network-specific statuses or funnel steps to internal event names so reporting and CAPI mappings stay consistent. Document your event taxonomy once and reuse across campaigns.

Self-hosted vs Cloud

More detail: Self-hosted page.

API documentation (selected endpoints)

All calls require authentication (JWT / session as configured for your deployment). Prefix: /api/v1.

# Tracking & conversions
GET  /api/v1/track/{campaign_id}     # redirect click
POST /api/v1/track?campaign_id=      # JSON click + redirect URL
GET  /api/v1/postback?click_id=...    # conversion (GET)
POST /api/v1/postback?click_id=...   # conversion (POST)

# Core entities (examples — use app + OpenAPI for full list)
GET  /api/v1/campaigns
GET  /api/v1/offers
GET  /api/v1/rules
GET  /api/v1/profit/dashboard?period=7d

# GEO Balancer + white pages
GET    /api/v1/geo-balancer
POST   /api/v1/geo-balancer
GET    /api/v1/geo-balancer/{id}
PUT    /api/v1/geo-balancer/{id}
DELETE /api/v1/geo-balancer/{id}
POST   /api/v1/geo-balancer/{id}/test
GET    /api/v1/geo-balancer/{id}/stats

GET    /api/v1/white-pages
POST   /api/v1/white-pages
GET    /api/v1/white-pages/{id}
PUT    /api/v1/white-pages/{id}
DELETE /api/v1/white-pages/{id}
GET    /wp/{slug}

# GEO analytics
GET /api/v1/campaigns/{id}/analytics
GET /api/v1/campaigns/{id}/analytics/geo-map

Troubleshooting

Conversions missing in the tracker

• Verify the network fires the postback (request logs / test conversion).
• Confirm the macro resolves to the same click_id VektraPulse issued.
• Check for URL encoding issues (special characters in tokens).

ROAS looks wrong

• Confirm spend import covers the same date range as revenue.
• Match currency and timezone.
• Exclude test postbacks from production campaigns.

CAPI not receiving events

• Workspace is the unified Affiliate workspace — CAPI is configured in the core sidebar, not in the Telegram Source area.
• Run each provider's test endpoint from Integrations.
• Ensure deduplication keys / event names match what the ad platform expects.

Clicks not redirecting

• Campaign inactive or destination URL empty.
• Monthly click limit reached (upgrade or wait for reset).
• Rule or fraud block triggered—check rule logs.

FAQ

Quick answers to the questions media buyers ask us most often.