Basic Usage Examples

Overview

This guide demonstrates the fundamental operations of the Switchport SDK:

Initializing the client
Executing prompts
Recording metrics
Working with different metric types

Setup

First, install the SDK and set your API key:

go get github.com/switchport-ai/switchport-go
export SWITCHPORT_API_KEY=sp_your_key_here

Example 1: Simple Prompt Execution

Execute a prompt without user identification or variables:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	// Initialize client
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Execute prompt
	response, err := client.Prompts.Execute(
		"welcome-message",
		nil, // no user
		nil, // no variables
	)
	if err != nil {
		log.Fatalf("Failed to execute prompt: %v", err)
	}

	fmt.Println("Generated text:")
	fmt.Println(response.Text)
	fmt.Printf("\nModel: %s\n", response.Model)
	fmt.Printf("Version: %s\n", response.VersionName)
}

Example 2: Prompt with Variables

Pass dynamic variables to your prompt:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	response, err := client.Prompts.Execute(
		"welcome-message",
		nil, // no user
		map[string]interface{}{
			"customer_name": "Alice",
			"product":       "Pro Plan",
		},
	)
	if err != nil {
		log.Fatalf("Failed to execute prompt: %v", err)
	}

	fmt.Println("Generated text:")
	fmt.Println(response.Text)
}

Make sure your prompt template in the dashboard includes the variables like {{customer_name}} and {{product}}.

Example 3: Prompt with User Identification

Use user identification for deterministic version assignment:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	response, err := client.Prompts.Execute(
		"product-description",
		map[string]interface{}{
			"user_id": "user_123",
			"tier":    "premium",
		},
		map[string]interface{}{
			"product_name": "Enterprise Widget",
		},
	)
	if err != nil {
		log.Fatalf("Failed to execute prompt: %v", err)
	}

	fmt.Printf("Version: %s\n", response.VersionName)
	fmt.Printf("Request ID: %s\n", response.RequestID)
	fmt.Printf("\n%s\n", response.Text)
}

Example 4: Recording a Float Metric

Track numerical values like satisfaction scores:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Record user satisfaction (1-5 scale)
	result, err := client.Metrics.Record(
		"user_satisfaction",
		4.5,
		map[string]interface{}{
			"user_id": "user_123",
			"tier":    "premium",
		},
		nil, // timestamp (nil = current time)
	)
	if err != nil {
		log.Fatalf("Failed to record metric: %v", err)
	}

	fmt.Printf("Metric recorded! Event ID: %s\n", result.MetricEventID)
}

Make sure you’ve created the metric definition in the dashboard before recording.

Example 5: Recording a Boolean Metric

Track yes/no events like conversions:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Track conversion
	result, err := client.Metrics.Record(
		"conversion_success",
		true,
		map[string]interface{}{
			"campaign_id": "summer_2025",
			"user_id":     "user_456",
		},
		nil,
	)
	if err != nil {
		log.Fatalf("Failed to record metric: %v", err)
	}

	fmt.Printf("Conversion tracked! Event ID: %s\n", result.MetricEventID)
}

Example 6: Recording an Enum Metric

Track categorical values:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Track user sentiment
	result, err := client.Metrics.Record(
		"user_sentiment",
		"positive", // Can be "positive", "neutral", "negative"
		map[string]interface{}{
			"feature": "new_ui",
			"user_id": "user_789",
		},
		nil,
	)
	if err != nil {
		log.Fatalf("Failed to record metric: %v", err)
	}

	fmt.Printf("Sentiment recorded! Event ID: %s\n", result.MetricEventID)
}

Example 7: Complete Workflow

Execute a prompt and record metrics:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Define subject identification for this user
	subject := map[string]interface{}{
		"user_id": "user_123",
		"tier":    "premium",
	}

	// Execute prompt
	response, err := client.Prompts.Execute(
		"welcome-message", subject,
		map[string]interface{}{
			"customer_name": "Alice",
		},
	)
	if err != nil {
		log.Fatalf("Failed to execute prompt: %v", err)
	}

	fmt.Println("Message sent to user:")
	fmt.Println(response.Text)
	fmt.Printf("\nVersion: %s\n", response.VersionName)

	// Simulate user interaction...
	userSatisfaction := 4.5

	// Record metric with same subject
	result, err := client.Metrics.Record(
		"user_satisfaction",
		userSatisfaction,
		subject, // Same subject!
		nil,
	)
	if err != nil {
		log.Fatalf("Failed to record metric: %v", err)
	}

	fmt.Printf("\nMetric recorded! Event ID: %s\n", result.MetricEventID)
	fmt.Println("This metric is linked to version:", response.VersionName)
}

Always use the same subject when executing prompts and recording metrics to ensure proper metric aggregation per version.

Example 8: String Subject

Use a simple string as subject:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Use string subject
	response, err := client.Prompts.Execute(
		"greeting",
		"guest_user", // String Subject
		nil,
	)
	if err != nil {
		log.Fatalf("Failed to execute prompt: %v", err)
	}

	fmt.Printf("Version: %s\n", response.VersionName)
	fmt.Println(response.Text)
}

Example 9: Error Handling

Handle errors gracefully:

package main

import (
	"errors"
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	response, err := client.Prompts.Execute(
		"my-prompt",
		nil,
		nil,
	)
	if err != nil {
		var promptNotFound *switchport.PromptNotFoundError
		var authErr *switchport.AuthenticationError

		switch {
		case errors.As(err, &promptNotFound):
			fmt.Println("Prompt not found - check your prompt key")
			// Use fallback
			fmt.Println("Using default message...")
			return
		case errors.As(err, &authErr):
			fmt.Println("Authentication failed - check your API key")
			return
		default:
			fmt.Printf("Unexpected error: %v\n", err)
			return
		}
	}

	fmt.Println(response.Text)
}

Example 10: Multiple Metrics

Record multiple metrics for the same user:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	subject := map[string]interface{}{
		"user_id":    "user_123",
		"session_id": "session_456",
	}

	// Record multiple related metrics
	_, err = client.Metrics.Record("satisfaction", 4.5, subject, nil)
	if err != nil {
		log.Printf("Failed to record satisfaction: %v", err)
	}

	_, err = client.Metrics.Record("conversion", true, subject, nil)
	if err != nil {
		log.Printf("Failed to record conversion: %v", err)
	}

	_, err = client.Metrics.Record("sentiment", "positive", subject, nil)
	if err != nil {
		log.Printf("Failed to record sentiment: %v", err)
	}

	fmt.Println("All metrics recorded for user_123!")
}

Next Steps

Advanced Examples

Explore advanced A/B testing patterns

Error Handling

Learn best practices for error handling

API Reference

View the complete API reference

Core Concepts

Understand key Switchport concepts

Getting Started

Core Features

Examples

Basic Usage Examples

Overview

Setup

Example 1: Simple Prompt Execution

Example 2: Prompt with Variables

Example 3: Prompt with User Identification

Example 4: Recording a Float Metric

Example 5: Recording a Boolean Metric

Example 6: Recording an Enum Metric

Example 7: Complete Workflow

Example 8: String Subject

Example 9: Error Handling

Example 10: Multiple Metrics

Next Steps

Advanced Examples

Error Handling

API Reference

Core Concepts

Getting Started

Core Features

Examples

​Overview

​Setup

​Example 1: Simple Prompt Execution

​Example 2: Prompt with Variables

​Example 3: Prompt with User Identification

​Example 4: Recording a Float Metric

​Example 5: Recording a Boolean Metric

​Example 6: Recording an Enum Metric

​Example 7: Complete Workflow

​Example 8: String Subject

​Example 9: Error Handling

​Example 10: Multiple Metrics

​Next Steps

Advanced Examples

Error Handling

API Reference

Core Concepts

Overview

Setup

Example 1: Simple Prompt Execution

Example 2: Prompt with Variables

Example 3: Prompt with User Identification

Example 4: Recording a Float Metric

Example 5: Recording a Boolean Metric

Example 6: Recording an Enum Metric

Example 7: Complete Workflow

Example 8: String Subject

Example 9: Error Handling

Example 10: Multiple Metrics

Next Steps