Embedded Onboarding

Edlink's embedded onboarding allows you to integrate the Edlink onboarding experience directly into your application, providing a seamless connection flow for educational systems like Canvas, Schoology, PowerSchool, and others.

This guide explains how to implement and use Edlink's embedded onboarding flow within your application.

Usage

1. Install the Edlink Widgets SDK

Add this script tag to your HTML to "install" the Edlink Widgets SDK:

<script src="https://ed.link/widgets/edlink.js"></script>

2. Initialize the Edlink Client

First, initialize the Edlink SDK with your client ID:

this.edlink = new Edlink({
    client_id: 'YOUR_APPLICATION_ID'
});

3. Create an Onboarding Instance

Create an onboarding instance with configuration options:

const options = {
    // Optional: Specify a provider to pre-select it
    provider: 'canvas', // Examples: 'canvas', 'schoology', etc.

    // Optional: Customize the theme
    theme: {
        primary_color: '#e63946' // Your brand color
    },

    // Optional: Tell Edlink the user's email; this creates a better user experience
    email: 'user@example.com',

    // Optional: Handle errors
    onError: (error) => {
        console.error('Onboarding error:', error);
        // Handle the error, e.g., show a message to the user
    },

    // Optional: Handle successful completion
    onSuccess: (data) => {
        console.log('Onboarding success:', data);
        // Handle the success, e.g., update UI to show connected status
    }
};

const onboarding = this.edlink.createOnboarding(options);

4. Listen for Events

Set up event listeners for user interactions:

// Optional: Listen for when user cancels
onboarding.on('integrate.cancel', () => {
    console.log('Onboarding cancelled by user');
    // Handle cancellation
});

// Optional: Listen for when onboarding is closed
onboarding.on('integrate.close', () => {
    console.log('Onboarding closed');
    // Handle close event
});

// Optional: Listen for errors
onboarding.on('integrate.error', (error) => {
    console.error('Onboarding error:', error);
    // Handle error
});

// Optional: Listen for successful integration
onboarding.on('integrate.success', (data) => {
    console.log('Integration successful:', data);
    // Handle successful integration
});

5. Show the Onboarding Flow

Display the onboarding modal:

onboarding.show();

6. Clean Up Resources

When your component is unmounted or the onboarding flow is no longer needed:

// In the component's destroyed/unmounted lifecycle hook
if (onboarding !== null && onboarding !== undefined) {
    onboarding.destroy();
}

Configuration Options

Events

Providers

You can get a list of supported providers by calling the /api/v1/providers endpoint. This will return a list of available providers that can be used in the onboarding process. The application value is what you should use for the provider parameter when creating the onboarding instance.

Example Implementation

Here's a complete example of implementing embedded onboarding in a Vue component:

export default {
    name: 'MyOnboardingComponent',
    data() {
        return {
            edlink: null,
            onboarding: null
        };
    },
    mounted() {
        this.edlink = new Edlink({
            client_id: 'YOUR_CLIENT_ID'
        });
    },
    destroyed() {
        if (this.onboarding) {
            this.onboarding.destroy();
        }
    },
    methods: {
        createOnboarding() {
            const options = {
                theme: {
                    primary_color: '#e63946'
                },
                email: this.state.user.email
            };

            this.onboarding = this.edlink.createOnboarding(options);

            this.onboarding.on('integrate.success', (data) => {
                // Handle successful integration
            });

            this.onboarding.on('integrate.error', (error) => {
                // Show error message to user or error page
                // Offer retry options
            });

            this.onboarding.on('integrate.cancel', () => {
                // User cancelled the onboarding
            });

            this.onboarding.on('integrate.close', () => {
                // Onboarding modal closed after completion
            });

            this.onboarding.show();
        }
    }
};

Best Practices

1. Error Handling: Always implement proper error handling in the onError callback or via events to provide feedback to users when something goes wrong.
2. Resource Cleanup: Call destroy() when the onboarding component is no longer needed to prevent memory leaks.
3. Responsive Design: Ensure your application layout accommodates the onboarding modal appropriately.
4. User Experience: Consider pre-filling the email field when the user's information is already known to reduce friction.
5. Provider Selection: Only specify a provider parameter when you want to skip the provider selection screen and direct users to a specific integration.
6. Custom Styling: Use the theme option to match the onboarding flow to your brand colors for a consistent user experience.