Onboarding¶

Overview¶

The Onboarding app provides a structured user introduction system for Jend-Z, guiding new users through their initial platform experience based on their stated intentions. The system collects user motivations, tracks progress through onboarding steps, and routes users to appropriate features to maximize engagement and platform adoption.

Data Models¶

OnboardingSession Model¶

The central OnboardingSession model tracks a user's complete onboarding journey.

Core Fields¶

id (UUID): Unique identifier
user (OneToOneField): Associated user account (CustomUser)
intent (CharField): User's stated platform intention
current_step (CharField): Current position in onboarding flow
is_completed (BooleanField): Completion status
started_at (DateTimeField): Onboarding initiation timestamp
completed_at (DateTimeField): Completion timestamp (optional)

User Intent Types¶

intent (CharField): Primary reason for joining platform

Available Intents:

create_community - "I want to start a community"
join_communities - "I want to join communities"
discover_content - "I want to discover local content"
start_business - "I want to promote my business"
connect_locally - "I want to connect with my neighborhood"
other - "Other"

Onboarding Steps¶

current_step (CharField): Current onboarding stage

Available Steps:

not_started - "Not Started"
intent_collection - "Collecting Intent"
location_setup - "Setting Up Location"
community_action - "Community Action"
profile_completion - "Profile Completion"
completed - "Completed"

Source Tracking¶

download_source (CharField): How user discovered the app
referral_source (CharField): Specific referral attribution

Progress Tracking¶

intent_collected (BooleanField): Intent collection completed
location_setup (BooleanField): Location setup completed
community_action_taken (BooleanField): Community action completed
profile_completed (BooleanField): Profile completion finished

Flow Logic Methods¶

def get_next_step(self):
    """Determine next step based on user intent"""

def mark_step_completed(self, step):
    """Mark specific step as completed and advance flow"""

def get_completed_steps(self):
    """Return list of completed onboarding steps"""

OnboardingAction Model¶

Tracks specific user actions during the onboarding process for analytics and debugging.

Core Fields¶

id (UUID): Unique identifier
session (ForeignKey): Associated onboarding session
action_type (CharField): Type of action performed
created_at (DateTimeField): Action timestamp

Action Types¶

intent_selected - "Intent Selected"
location_set - "Location Set"
community_created - "Community Created"
community_joined - "Community Joined"
profile_updated - "Profile Updated"
onboarding_skipped - "Onboarding Skipped"

Action Metadata¶

target_id (UUIDField): ID of related object (community, post, etc.)
target_type (CharField): Type of related object
additional_info (TextField): Extra action details

API Endpoints¶

Onboarding Flow Management¶

1. Start Onboarding¶

Endpoint: POST /api/onboarding/start/

Authentication: Bearer token required

Description: Initialize or resume onboarding process for current user.

Request Body: Empty

Success Response:

{
  "message": "Onboarding started",
  "session": {
    "id": "session-uuid",
    "intent": null,
    "current_step": "intent_collection",
    "is_completed": false,
    "download_source": null,
    "referral_source": null,
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": null,
    "intent_collected": false,
    "location_setup": false,
    "community_action_taken": false,
    "profile_completed": false
  }
}

Already Completed Response:

{
  "message": "Onboarding already completed",
  "session": {
    "id": "session-uuid",
    "intent": "join_communities",
    "current_step": "completed",
    "is_completed": true,
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T11:45:00Z"
  }
}

2. Set User Intent¶

Endpoint: POST /api/onboarding/intent/

Authentication: Bearer token required

Description: Collect user's primary platform intention and advance onboarding flow.

Request Body:

{
  "intent": "join_communities",
  "download_source": "instagram_ad",
  "referral_source": "friend_recommendation"
}

Required Fields:

intent: Must be one of the valid intent choices

Success Response:

{
  "message": "Intent set successfully",
  "next_step": "community_action",
  "session": {
    "id": "session-uuid",
    "intent": "join_communities",
    "current_step": "community_action",
    "is_completed": false,
    "download_source": "instagram_ad",
    "referral_source": "friend_recommendation",
    "intent_collected": true,
    "location_setup": false,
    "community_action_taken": false,
    "profile_completed": false
  }
}

Intent Flow Logic:

create_community → community_action
join_communities → community_action
discover_content → location_setup
start_business → profile_completion
connect_locally → location_setup
other → profile_completion

3. Get Onboarding Status¶

Endpoint: GET /api/onboarding/status/

Authentication: Bearer token required

Description: Retrieve current user's onboarding progress and status.

Response:

{
  "id": "session-uuid",
  "intent": "create_community",
  "current_step": "community_action",
  "is_completed": false,
  "download_source": "google_search",
  "referral_source": null,
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": null,
  "intent_collected": true,
  "location_setup": false,
  "community_action_taken": false,
  "profile_completed": false
}

No Session Response:

{
  "message": "No onboarding session found",
  "onboarding_required": true
}

4. Complete Onboarding¶

Endpoint: POST /api/onboarding/complete/

Authentication: Bearer token required

Description: Mark onboarding process as completed.

Request Body: Empty

Success Response:

{
  "message": "Onboarding completed successfully",
  "session": {
    "id": "session-uuid",
    "intent": "join_communities",
    "current_step": "completed",
    "is_completed": true,
    "completed_at": "2024-01-15T11:45:00Z"
  }
}

5. Skip Onboarding¶

Endpoint: POST /api/onboarding/skip/

Authentication: Bearer token required

Description: Allow users to bypass onboarding and explore platform independently.

Request Body: Empty

Success Response:

{
  "message": "Onboarding skipped successfully"
}

Side Effects:

Creates or updates onboarding session
Logs skip action with current step context
Marks onboarding as completed
Allows immediate platform access

Onboarding Flow Logic¶

Intent-Based Routing¶

The onboarding system routes users through different experiences based on their stated intentions:

Community Creation Flow¶

Intent: create_community Steps: Intent Collection → Community Action → Profile Completion → Complete

Process:

User selects "I want to start a community"
System directs to community creation form
After community creation, completes profile setup
Onboarding finished

Community Discovery Flow¶

Intent: join_communities Steps: Intent Collection → Community Action → Profile Completion → Complete

Process:

User selects "I want to join communities"
System shows curated community recommendations
User joins one or more communities
Profile completion and onboarding finished

Content Discovery Flow¶

Intent: discover_content Steps: Intent Collection → Location Setup → Profile Completion → Complete

Process:

User selects "I want to discover local content"
System requests location permissions
Location-based content feed setup
Profile completion and onboarding finished

Business Promotion Flow¶

Intent: start_business Steps: Intent Collection → Profile Completion → Complete

Process:

User selects "I want to promote my business"
Enhanced profile setup with business focus
Introduction to store creation features
Onboarding finished

Local Connection Flow¶

Intent: connect_locally Steps: Intent Collection → Location Setup → Profile Completion → Complete

Process:

User selects "I want to connect with my neighborhood"
Location setup and neighborhood discovery
Local user recommendations
Profile completion and onboarding finished

Progress Tracking¶

Each onboarding step updates specific boolean fields:

Step Completion Mapping¶

step_mapping = {
    'intent_collection': 'intent_collected',
    'location_setup': 'location_setup',
    'community_action': 'community_action_taken',
    'profile_completion': 'profile_completed'
}

Completion Logic¶

Individual steps marked as boolean flags
Current step advances automatically
Analytics track completion rates per step
Users can resume from last completed step

Integration with Other Apps¶

Communities Integration¶

Community Creation Onboarding:

// Create community with onboarding context
POST /
  api /
  communities /
  communities /
  {
    name: "Lagos Tech Meetup",
    description: "Weekly tech meetups in Lagos",
    category: "category-uuid",
    onboarding: true, // Indicates onboarding flow
  };

// After creation, mark onboarding step complete
POST / api / onboarding / complete -
  step /
    {
      step: "community_action",
      action_type: "community_created",
      target_id: "new-community-uuid",
    };

Community Discovery Integration:

// Get onboarding-optimized community suggestions
GET /api/communities/communities/onboarding_suggestions/

// Track community joins during onboarding
POST /api/communities/communities/{id}/join/
// Automatically logs onboarding action

Location Integration¶

Location Setup Flow:

// Set user location during onboarding
POST / api / update -
  location /
    {
      country: "Nigeria",
      state: "Lagos State",
      city: "Lagos",
      neighbourhood: "Victoria Island",
      onboarding: true,
    };

// Mark location setup complete
POST / api / onboarding / complete -
  step /
    {
      step: "location_setup",
      action_type: "location_set",
    };

User Profile Integration¶

Profile Completion Flow:

// Update profile during onboarding
PATCH /
  api /
  profile /
  update /
  {
    display_name: "John Developer",
    bio: "Software developer passionate about Nigerian tech",
    profile_picture: "image_file",
    onboarding: true,
  };

Analytics and Tracking¶

Onboarding Metrics¶

The system tracks comprehensive analytics for onboarding optimization:

Completion Rates¶

Overall Completion: Percentage of users completing full onboarding
Step-by-Step: Completion rates for individual steps
Intent-Based: Completion rates by user intent type
Time-to-Complete: Average time spent in onboarding

Drop-off Analysis¶

Abandonment Points: Where users most commonly exit onboarding
Intent Correlation: Which intents have highest completion rates
Source Performance: Completion rates by download/referral source

Action Tracking¶

User Actions: Specific actions taken during onboarding
Path Analysis: Common paths through onboarding flow
Skip Patterns: When and why users skip onboarding

Analytics Queries¶

# Completion rate by intent
completion_by_intent = OnboardingSession.objects.values('intent').annotate(
    total=models.Count('id'),
    completed=models.Count('id', filter=models.Q(is_completed=True))
)

# Average time to completion
from django.db.models import Avg
avg_completion_time = OnboardingSession.objects.filter(
    is_completed=True
).annotate(
    duration=models.F('completed_at') - models.F('started_at')
).aggregate(Avg('duration'))

# Most common drop-off points
dropoff_analysis = OnboardingSession.objects.filter(
    is_completed=False
).values('current_step').annotate(
    count=models.Count('id')
).order_by('-count')

Frontend Implementation¶

React/JavaScript Integration¶

Onboarding Flow Management¶

// Check if onboarding is required
const checkOnboardingStatus = async () => {
  try {
    const response = await api.get("/api/onboarding/status/");
    return response.data;
  } catch (error) {
    if (error.response?.data?.onboarding_required) {
      return { onboarding_required: true };
    }
    throw error;
  }
};

// Start onboarding process
const startOnboarding = async () => {
  const response = await api.post("/api/onboarding/start/");
  return response.data.session;
};

// Set user intent
const setUserIntent = async (intent, sources = {}) => {
  const response = await api.post("/api/onboarding/intent/", {
    intent,
    download_source: sources.download,
    referral_source: sources.referral,
  });
  return response.data;
};

const routeUserByStep = (session) => {
  const { current_step, intent } = session;

  switch (current_step) {
    case "intent_collection":
      return "/onboarding/welcome";

    case "community_action":
      if (intent === "create_community") {
        return "/onboarding/create-community";
      } else if (intent === "join_communities") {
        return "/onboarding/discover-communities";
      }
      break;

    case "location_setup":
      return "/onboarding/location";

    case "profile_completion":
      return "/onboarding/profile";

    case "completed":
      return "/dashboard";

    default:
      return "/onboarding/welcome";
  }
};

Progressive Enhancement¶

// Track step completion
const completeOnboardingStep = async (step, actionData = {}) => {
  // Mark step as complete
  await api.post("/api/onboarding/complete-step/", {
    step,
    ...actionData,
  });

  // Get updated status
  const status = await checkOnboardingStatus();

  // Route to next step
  const nextRoute = routeUserByStep(status);
  router.push(nextRoute);
};

Error Handling¶

Common Error Responses¶

Invalid Intent:

{
  "intent": ["\"invalid_intent\" is not a valid choice."]
}

Session Not Found:

{
  "detail": "OnboardingSession matching query does not exist."
}

Already Completed:

{
  "message": "Onboarding already completed",
  "session": { "is_completed": true }
}

Authentication Required:

{
  "detail": "Authentication credentials were not provided."
}

HTTP Status Codes¶

200 OK: Successful operation
201 Created: Session created successfully
400 Bad Request: Invalid intent or request data
401 Unauthorized: Authentication required
404 Not Found: Session not found
500 Internal Server Error: Server error

Onboarding¶

Overview¶

Data Models¶

OnboardingSession Model¶

Core Fields¶

User Intent Types¶

Onboarding Steps¶

Source Tracking¶

Progress Tracking¶

Flow Logic Methods¶

OnboardingAction Model¶

Core Fields¶

Action Types¶

Action Metadata¶

API Endpoints¶

Onboarding Flow Management¶

1. Start Onboarding¶

2. Set User Intent¶

3. Get Onboarding Status¶

4. Complete Onboarding¶

5. Skip Onboarding¶

Onboarding Flow Logic¶

Intent-Based Routing¶

Community Creation Flow¶

Community Discovery Flow¶

Content Discovery Flow¶

Business Promotion Flow¶

Local Connection Flow¶

Progress Tracking¶

Step Completion Mapping¶

Completion Logic¶

Integration with Other Apps¶

Communities Integration¶

Location Integration¶

User Profile Integration¶

Analytics and Tracking¶

Onboarding Metrics¶

Completion Rates¶

Drop-off Analysis¶

Action Tracking¶

Analytics Queries¶

Frontend Implementation¶

React/JavaScript Integration¶

Onboarding Flow Management¶

Step-by-Step Navigation¶

Progressive Enhancement¶

Error Handling¶

Common Error Responses¶

HTTP Status Codes¶