Getting Started

This guide will help you get started with Upod in just a few minutes. We'll cover the basics and help you choose the right integration path.

Prerequisites

Before you begin, you'll need:

1. A website or web application where you want to integrate Upod
2. Contact us via email to register your application as an OIDC client
3. Basic knowledge of JavaScript/HTML (helpful but not required)

Step 1: Register Your Application

Important: Before you can integrate Upod, you must register your application as a new OIDC client. This can be done by contacting us via email.

1. Contact us via email to request OIDC client registration
2. Provide us with:
   • Your website URL(s)
   • The redirect URI(s) where users will return after login
3. We'll register your client_id and redirect_uri(s)
4. You'll receive your client_id which you'll use in your integration

Step 2: Choose Your Integration Path

Upod offers multiple integration approaches. Choose the one that best fits your needs:

All integration paths result in:

• ✅ Authenticated users - Users can log in securely via Upod
• ✅ Anonymized user data - Access to user profile data (gender, age range, residence) without personal identifiers
• ✅ Privacy-first - No cookies required, user data is anonymized and stored securely

Redirect and logout URIs

For every aforementioned path and the quick start below, registered redirect_uri and post_logout_redirect_uri values must match what your app sends exactly (same string, including path and trailing slash). For example, https://example.com and https://example.com/ count as different URIs. The guides use location.origin + location.pathname in examples, which usually matches how the browser reports the current page (for the site root, that is often https://your-domain/).

Quick Start Example

Here's a minimal example to get you started:

Install the Client Library

Include the Upod client library in your HTML:

<script src="https://cdn.upod.eu/client/bundle.browser.js"></script>

Initialize Upod

Initialize the client with your credentials:

<script>
    const client = upod.initialize({
        authority: 'https://account.upod.eu',
        client_id: 'your-client-id', // Obtained by contacting us
        redirect_uri: location.origin + location.pathname,
        post_logout_redirect_uri: location.origin + location.pathname,
    });
</script>

Handle Authentication

Handle the OIDC callback and check authentication status:

client.handleCallbackIfNeeded().then(() => {
    client.isAuthenticated().then(loggedIn => {
        if (loggedIn) {
            // User is logged in
            loadPersonalizedContent();
        } else {
            // User is not logged in
            loadGenericContent();
        }
    });
});

Fetch User Profile Data

Once authenticated, fetch anonymized user profile data:

client.onLogin(() => {
    client
        .fetch({
            path: '/storage/profile',
            method: 'get',
            query: { purpose: 'personalisation' },
        })
        .then(profile => {
            console.log('Gender:', profile.gender);
            console.log('Age Range:', profile.ageRange);
            console.log('Residence:', profile.residence);

            // Use profile data to personalize content
        });
});

The storage API expects purpose as a query string parameter, so the client library takes it inside query (not as a top-level fetch option). Full parameter list: client.fetch(options) in the API Reference.

Backend and server-side code: client.fetch() only runs in the browser with an active Upod session from this client library. It cannot be used from PHP, a generic HTTP proxy, or other server-only code. To give a backend anonymized profile context, fetch the profile in the browser after login and send the fields you need to your own API. See Server-side and backend use in the API Reference.

Next Steps

1. Choose an integration path from the options above
2. Follow the specific integration guide for your chosen path
3. Review the API Reference to understand data formats and available methods
4. Test your integration using our live examples

Need Help?

• Review the API Reference for detailed information
• Check out a basic client integration.
• Check out our live examples
• Contact us if you need assistance with your integration