Profile photos with Gravatar

Gravatar is a global avatar service that links a profile photo to an email address. A user uploads a photo once, and every site or app that looks up the hash of their email address shows the same picture.

How does the integration work?

Appwrite Avatars looks up Gravatar for you through the user photos endpoint. One getPhoto call returns the best available profile photo for a user, and Gravatar is one of the sources Appwrite checks. It comes after a photo from the user's OAuth2 identity and before Libravatar, initials, and a built-in placeholder.

Appwrite queries Gravatar with the SHA-256 hash of the user's trimmed, lowercase email address, so you don't need a Gravatar account or API key. When Gravatar has no photo for a hash, Appwrite moves on to the next source, so the call always returns an image.

How to implement

To show Gravatar photos with Appwrite Avatars, there are several steps you must complete:

Step 1: Show the signed-in user's photo

For this step, you must create an account on Appwrite Cloud or self-host Appwrite if you haven't already. Pass current() as the userId to get the photo of the user who is signed in. If they have a Gravatar for their email address and no higher-priority photo, such as one from an OAuth2 identity, Appwrite returns their Gravatar.

import { Client, Avatars } from "appwrite";

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>');

const avatars = new Avatars(client);

const result = avatars.getPhoto({
    userId: 'current()',
    width: 128,
    height: 128
});

console.log(result); // Resource URL

The Web SDK returns a URL that you can use as the src of an <img> tag. Pass another user's ID instead of current() to show their photo, for example next to a comment or in a member list.

Step 2: Show photos for people who aren't users yet

To show an avatar for someone who doesn't have an account in your project, such as an invitee, pass an emailHash and a name. The emailHash is the SHA-256 hash of the email address, trimmed and lowercased, as a 64-character hex string. Appwrite only accepts the hash, so the address itself never appears in a URL.

async function hashEmail(email) {
    const data = new TextEncoder().encode(email.trim().toLowerCase());
    const digest = await crypto.subtle.digest('SHA-256', data);
    return Array.from(new Uint8Array(digest))
        .map((byte) => byte.toString(16).padStart(2, '0'))
        .join('');
}

const result = avatars.getPhoto({
    emailHash: await hashEmail('walter@example.com'),
    name: 'Walter White',
    width: 128,
    height: 128
});

Appwrite looks the hash up on Gravatar and Libravatar, renders the name as initials if neither has a photo, and falls back to the placeholder.

Step 3: Limit the image rating

Gravatar rates every image as g, pg, r, or x. Use the rating parameter to set the highest rating Appwrite accepts. It defaults to g, the most restrictive rating.

const result = avatars.getPhoto({
    userId: 'current()',
    rating: 'pg'
});

Appwrite sends every photo with Cache-Control: private, no-store, so a user's new Gravatar shows up the next time the image loads.

Read more about Gravatar and Appwrite Avatars

If you would like to learn more about Gravatar and Appwrite Avatars, we have some resources that you should visit: