Session Management

Access player session data for advanced integrations. Sessions track when players join, their connection details, and their analytics session ID.

Quick Start

import net.analyse.api.Analyse;
import net.analyse.api.manager.SessionManager;
import net.analyse.api.session.PlayerSession;

SessionManager sessions = Analyse.sessions();

// Get a player's session
sessions.getSession(player.getUniqueId()).ifPresent(session -> {
    System.out.println("Hostname: " + session.getHostname());
    System.out.println("Joined: " + session.getJoinTime());
});

SessionManager

The SessionManager provides access to all active player sessions.

Get a Player's Session

Optional<? extends PlayerSession> optionalSession = Analyse.sessions().getSession(uuid);

if (optionalSession.isPresent()) {
    PlayerSession session = optionalSession.get();
    // Use session data
}

Or with ifPresent:

Analyse.sessions().getSession(uuid).ifPresent(session -> {
    String hostname = session.getHostname();
    // Process session
});

Check if Player Has Session

if (Analyse.sessions().hasSession(player.getUniqueId())) {
    // Player is tracked
}

Get All Active Sessions

Collection<? extends PlayerSession> allSessions = Analyse.sessions().getAllSessions();

for (PlayerSession session : allSessions) {
    System.out.println(session.getPlayerUuid() + " - " + session.getHostname());
}

Get Session Count

int onlinePlayers = Analyse.sessions().getSessionCount();

PlayerSession

Each session provides access to player connection data.

Available Data

Method	Returns	Description
`getPlayerUuid()`	`UUID`	Player's unique ID
`getSessionId()`	`String`	Analytics session ID from API
`getHostname()`	`String`	Hostname player connected with
`getIp()`	`String`	Player's IP address
`getJoinTime()`	`Instant`	When the player joined
`hasActiveSession()`	`boolean`	If registered with the API

Example: Get All Session Data

Analyse.sessions().getSession(player.getUniqueId()).ifPresent(session -> {
    UUID uuid = session.getPlayerUuid();
    String sessionId = session.getSessionId();
    String hostname = session.getHostname();
    String ip = session.getIp();
    Instant joinTime = session.getJoinTime();
    boolean active = session.hasActiveSession();
    
    System.out.println("Player: " + uuid);
    System.out.println("Session ID: " + sessionId);
    System.out.println("Connected via: " + hostname);
    System.out.println("IP: " + ip);
    System.out.println("Joined at: " + joinTime);
    System.out.println("Active: " + active);
});

Use Cases

Campaign Attribution in Plugins

Detect which campaign a player came from:

@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
    Player player = event.getPlayer();
    
    Analyse.sessions().getSession(player.getUniqueId()).ifPresent(session -> {
        String hostname = session.getHostname();
        
        // Check for campaign-specific hostnames
        if (hostname.startsWith("pewds.")) {
            givePewdiepieReward(player);
        } else if (hostname.startsWith("dream.")) {
            giveDreamReward(player);
        }
    });
}

Playtime Calculation

Calculate how long a player has been online:

public Duration getPlaytime(UUID uuid) {
    return Analyse.sessions().getSession(uuid)
        .map(session -> Duration.between(session.getJoinTime(), Instant.now()))
        .orElse(Duration.ZERO);
}

// Usage
Duration playtime = getPlaytime(player.getUniqueId());
long minutes = playtime.toMinutes();
player.sendMessage("You've been online for " + minutes + " minutes");

Session-Based Rewards

Give rewards based on session length:

public void checkPlaytimeRewards(Player player) {
    Analyse.sessions().getSession(player.getUniqueId()).ifPresent(session -> {
        Duration playtime = Duration.between(session.getJoinTime(), Instant.now());
        
        if (playtime.toMinutes() >= 60 && !hasReceivedReward(player, "1hour")) {
            giveReward(player, "1hour");
            player.sendMessage("Thanks for playing for 1 hour!");
        }
        
        if (playtime.toMinutes() >= 180 && !hasReceivedReward(player, "3hour")) {
            giveReward(player, "3hour");
            player.sendMessage("3 hours! Here's a special reward!");
        }
    });
}

Hostname-Based Server Selection

Route players based on how they connected:

@EventHandler
public void onServerConnect(ServerConnectEvent event) {
    Player player = event.getPlayer();
    
    Analyse.sessions().getSession(player.getUniqueId()).ifPresent(session -> {
        String hostname = session.getHostname();
        
        // Route to specific servers based on hostname
        if (hostname.contains("pvp.")) {
            event.setTarget(getServer("pvp-lobby"));
        } else if (hostname.contains("creative.")) {
            event.setTarget(getServer("creative"));
        }
    });
}

Admin Commands

Build admin tools with session info:

@CommandAlias("playerinfo")
public void onPlayerInfo(CommandSender sender, @Flags("other") Player target) {
    Analyse.sessions().getSession(target.getUniqueId()).ifPresent(session -> {
        sender.sendMessage("=== Player Info ===");
        sender.sendMessage("UUID: " + session.getPlayerUuid());
        sender.sendMessage("Hostname: " + session.getHostname());
        sender.sendMessage("IP: " + session.getIp());
        sender.sendMessage("Session ID: " + session.getSessionId());
        sender.sendMessage("Online since: " + session.getJoinTime());
    });
}

Best Practices

Always Check Availability

if (!Analyse.isAvailable()) {
    return;
}

Analyse.sessions().getSession(uuid).ifPresent(session -> {
    // Safe to use
});

Use Optional Properly

// ✅ Good - handle missing session
Analyse.sessions().getSession(uuid)
    .ifPresentOrElse(
        session -> processSession(session),
        () -> handleNoSession()
    );

// ✅ Good - with default value
String hostname = Analyse.sessions().getSession(uuid)
    .map(PlayerSession::getHostname)
    .orElse("unknown");

// ❌ Bad - unchecked get
PlayerSession session = Analyse.sessions().getSession(uuid).get();  // May throw!

Don't Store Session References

Sessions are valid only while the player is online:

// ❌ Bad - storing session reference
private Map<UUID, PlayerSession> cachedSessions = new HashMap<>();

// ✅ Good - get fresh each time
Analyse.sessions().getSession(uuid).ifPresent(session -> {
    // Use immediately
});

Next Steps

A/B Testing

Plugin Messaging