Overview
This is the documentation for the legacy ZK Email SDK. For the latest version, please see the Blueprint SDK page.
Getting started
Google Client API key: You will need a Google OAuth token if you want users to be able to directly query emails from their inbox. Go to Google Cloud's dashboard to enable the Gmail API.
Learn how to create your GOOGLE_CLIENT_ID
here.
React Project: The SDK currently only works with reactjs
. If you are using nextjs
, you might need some workarounds to make sure the page you integrate the SDK runs fully on the client side. Refer to this for reference example.
Wiring it up
Surround a page with the ZkEmailSDKProvider
given by the SDK. If you are using nextjs
, it is recommended that you only include this in a page that uses the SDK. Else, your entire application will need to be client-side rendered.
import { ZkEmailSDKProvider } from "@zk-email/zk-email-sdk";
function TryPage(props: Props) {
return (
<ZkEmailSDKProvider clientId={GOOGLE_CLIENT_ID} zkEmailSDKRegistryUrl='https://registry-dev.zkregex.com'>
<Page {...props}/>
</ZkEmailSDKProvider>
);
};
In your page, the SDK exposes a few hooks to interact with the library.
export function Page(props: Props) {
const {
googleAuthToken,
isGoogleAuthed,
loggedInGmail,
googleLogIn,
googleLogOut,
} = useGoogleAuth();
const {
createInputWorker,
generateInputFromEmail,
generateProofRemotely,
proofStatus,
inputWorkers
} = useZkEmailSDK();
}
Hook | Type | Arguments | Description |
---|---|---|---|
googleAuthToken | string | - | |
isGoogleAuthed | boolean | - | |
loggedInGmail | string | - | User's email |
googleLogIn | method | - | Triggers the OAuth page for users to login |
googleLogOut | method | - | Deletes the credentials stored in local browser |
createInputWorker | method | pattern ID | Creates a worker in the background that processes emails into circuit inputs. This always happens on the client side. It downloads a worker script from the registry and runs it in a sandboxed WebWorker. |
generateInputFromEmail | method | pattern ID, raw email | Returns the circuit input generated by processing the email provided |
generateProofRemotely | method | pattern ID, circuit input | Uses the circuit input generated and queues a job. Circuit inputs are stored only before/during proof generation. This will automatically poll the server for updates. |
proofStatus | {[key:string]: ProofStatus} | - | A map of proof job IDs and the current status + proof outputs. |
inputWorkers | {[key: string]: Worker} | - | A map of input worker slugs and their associated web workers. |
interface ProofStatus {
status: string;
id: string;
pollUrl: string;
estimatedTimeLeft: number;
publicOutput: any;
proof: any;
}
Example integration
First, create an inputWorker
:
createInputWorker("<slug-name>");
Once the input worker is created, it will be populated in the inputWorkers
variable. You can monitor this variable. As soon as the inputWorker is created, you can call the generateProofRemotely
method:
const [externalInputs, setExternalInputs] = useState<Record<string,string>>({});
// externalInputs - External inputs added when submitting a new pattern at https://registry-dev.zkregex.com/submit
const entryExternalInputs = externalInputs as {name: string, maxLength: number}[] || [];
for (const input of entryExternalInputs) {
setExternalInputs({
...externalInputs,
[input.name]: "",
});
}
const input = await generateInputFromEmail(
"<slug-name>",
emailFull,
externalInputs
);
const proofRes = await generateProofRemotely(
"<slug-name>",
input
);