HEARTBEAT

Establishes a secure connection to the authentication server and initializes the security system.

Critical: This function must be called before any other authentication operations.

Signature

bool SendHeartbeat();

Parameters

None - This function takes no parameters.

Returns

Type: bool

Value	Description
true	Connection established successfully
false	Connection failed

Description

SendHeartbeat performs multiple critical operations:

1

Connects to Server

Establishes TCP connection.

2

Performs Handshake

Encrypted key exchange.

3

Sends HWID

Registers hardware information.

4

Receives Settings

Gets security configuration.

5

Integrity Check

Verifies application integrity (if enabled).

6

Blacklist Check

Checks for blacklisted processes/windows (if enabled).

7

Background Monitoring

Starts security monitoring threads.

This function must be called after Init() and before any other operations.

Basic Example

qPapel::ProtectedAuth auth;
auth.Init(config);

if (auth.SendHeartbeat()) {
    std::cout << "Connected successfully!" << std::endl;
    // Proceed with authentication
} else {
    std::cerr << "Connection failed: " << auth.GetLastError() << std::endl;
    return 1;
}

What Happens Behind the Scenes

1. Connection

Connection

• Connects to authentication server

• Uses encrypted channel

Timeout: 10 seconds

Errors:

• "Socket creation failed"

• "Connection timeout"

• "Server unreachable"

2. Handshake

3. HWID Registration

4. Security Settings

5. Integrity Check

6. Blacklist Check

Complete Example

#include <iostream>
#include "qPapel.h"

int main() {
    // Step 1: Configure
    qPapel::AuthConfig config;
    config.apiKey = "pk_your_api_key";
    config.productSecretKey = "your_secret_key";
    config.productHmacKey = "your_hmac_key";
    
    // Step 2: Initialize
    qPapel::ProtectedAuth auth;
    auth.Init(config);
    
    std::cout << "Connecting to authentication server..." << std::endl;
    
    // Step 3: Connect
    if (auth.SendHeartbeat()) {
        std::cout << "Connection established!" << std::endl;
        std::cout << "Security systems active." << std::endl;
        
        // Now you can use other functions
        // ValidateKey, GetKeyInfo, GetServerString, etc.
        
    } else {
        std::cerr << "Connection failed!" << std::endl;
        std::cerr << "Error: " << auth.GetLastError() << std::endl;
        
        // Handle connection failure
        return 1;
    }
    
    return 0;
}

Error Handling

if (!auth.SendHeartbeat()) {
    std::string error = auth.GetLastError();
    
    if (error.find("Socket") != std::string::npos) {
        std::cout << "Network error - check internet connection" << std::endl;
    }
    else if (error.find("timeout") != std::string::npos) {
        std::cout << "Connection timeout - server may be down" << std::endl;
    }
    else if (error.find("denied") != std::string::npos) {
        std::cout << "Access denied - check API key" << std::endl;
    }
    else if (error.find("Integrity") != std::string::npos) {
        std::cout << "Integrity check failed - file modified" << std::endl;
    }
    else if (error.find("Blacklist") != std::string::npos) {
        std::cout << "Blacklisted software detected" << std::endl;
    }
    else {
        std::cout << "Error: " << error << std::endl;
    }
    
    return 1;
}

Common Errors

Socket creation failed

Cause: Network initialization error

Solutions:

• Check internet connection

• Verify firewall settings

• Ensure Windows Sockets initialized

• Check antivirus blocking

Connection timeout

Cause: Cannot reach server

Solutions:

• Verify server is running

• Check SERVER_IP and SERVER_PORT

• Test network connectivity

• Check firewall rules

Access denied

Cause: Invalid API key

Solutions:

• Verify API key is correct

• Check key is for correct application

• Ensure key is not expired

• Copy key again from dashboard

Integrity check failed

Cause: Application file modified

Solutions:

• Re-download original file

• Update expected hash in dashboard

• Disable integrity check for testing

• Check for file corruption

Blacklisted process detected

Cause: Forbidden software running

Solutions:

• Close blacklisted applications

• Check dashboard blacklist settings

• Remove from blacklist if legitimate

• Disable blacklist for testing

When to Call SendHeartbeat

Application Startup

int main() {
    qPapel::ProtectedAuth auth;
    auth.Init(config);
    
    // Call immediately after Init
    if (!auth.SendHeartbeat()) {
        return 1;
    }
    
    // Continue with application
}

Recommended: Call once at startup

Periodic Refresh

After Network Change

Performance Considerations

Execution Time

SendHeartbeat typically takes 100-500ms depending on:

• Network latency

• Server load

• Integrity check (if enabled)

• Blacklist scan (if enabled)

Synchronous

// Blocks until complete
if (auth.SendHeartbeat()) {
    // Connection established
}

Use when: Application startup, before critical operations

Async (Advanced)

Security Features Activated

After successful SendHeartbeat:

Feature	Description	Configured In
Integrity Check	SHA256 file verification	Dashboard → Applications → Integrity
Blacklist Protection	Process/window monitoring	Dashboard → Applications → Blacklist
Background Monitoring	Continuous security checks	Automatic
HWID Binding	Hardware identification	Dashboard → Applications → HWID

Web Dashboard Configuration

Security settings are configured in Dashboard → Applications

Enable Integrity Check

1. Go to Dashboard → Applications

2. Select your application

3. Navigate to Integrity tab

4. Enable Integrity Check

5. Upload your executable

6. Hash is calculated automatically

7. Choose detection action (Close App / BSOD)

Configure Blacklist

1. Go to Dashboard → Applications

2. Select your application

3. Navigate to Blacklist tab

4. Add blacklisted processes (e.g., "cheatengine.exe")

5. Add blacklisted windows (e.g., "Cheat Engine")

6. Choose detection action (Close App / BSOD)

Best Practices

1

Initialize first

Call Init() first.

2

SendHeartbeat next

Call SendHeartbeat() immediately after.

3

Check return value

Verify the return value before proceeding.

4

Handle errors

Handle errors gracefully.

5

User-friendly messages

Show user-friendly error messages.

Don't

• Call SendHeartbeat multiple times unnecessarily

• Ignore return value

• Proceed without successful connection

• Call before Init()

Related Functions

• Init - Initialize library (call before SendHeartbeat)

• ValidateKey - Validate license (call after SendHeartbeat)