SDK Integration Checklist
Integrated generator-sdk but something is not working and you don't know where to start?
This page organizes the most common problems by SDK module. Each problem comes with a ready-to-use prompt — copy it, fill in your project path, and send it to AI. The AI will inspect your code and fix what is missing.
SDK Initialization
Problem 1: The SDK has no effect — none of the features work
Send the following to AI:
Please inspect my generator project and find out why the SDK has no effect after integration.
All SDK features are unresponsive.
Project path: <your project path>
Check in this order:
1. Check whether GeneratorSDK.init({ appKey: '...' }) is called to initialize the SDK
2. Check whether appKey has a value (must not be empty or undefined)
3. Check whether the SDK is initialized before any other SDK calls (it must be first)
4. Check whether the browser console shows the "[GeneratorSDK] initialized" log — if not, initialization is not running
For each item: report the current status and fix directly if there is a problem.Problem 2: Multiple SDK instances are created — features behave inconsistently
Send the following to AI:
Please inspect my generator project for duplicate SDK instance initialization.
Different SDK features (for example login state and credits balance) behave inconsistently, possibly due to multiple instances.
Project path: <your project path>
Check the following:
1. Search the project for all GeneratorSDK.init calls
2. Check whether different locations use different appKey or env parameters — the same appKey+env combination is required to reuse the singleton
3. If multiple initializations with different parameters exist, find the correct one and unify all locations to use the same initialization config
4. Ensure initialization runs only once at the top level and the instance is passed down to wherever it is needed
Tell me where you made changes after fixing.Problem 3: Login state works in dev/test but not in prod (or vice versa)
Send the following to AI:
Please inspect my generator project for an SDK environment config issue.
Login state works correctly in dev/test but not in prod (or the other way around).
Project path: <your project path>
Check the following:
1. Check the env parameter in GeneratorSDK.init — valid values are: prod, prod_cn, pre, test, dev
2. Check whether the env parameter matches the current runtime environment (for example, using prod during local development sends requests to the live server)
3. Check whether the project has logic to dynamically switch the env parameter based on the runtime environment
4. If not, help me set the env parameter dynamically based on an environment variable such as import.meta.env.MODE or process.env.NODE_ENV
Tell me where you made changes after fixing.Auth Module
Problem 4: After page load, a logged-in user appears as logged out
Send the following to AI:
Please inspect my generator project for an Auth module session restore issue.
After a page refresh, a logged-in user appears as logged out.
Project path: <your project path>
Check the following:
1. Check whether sdk.auth.ready() is awaited after SDK initialization
2. Check whether the logic that renders the login state runs after ready() resolves
3. If ready() is not awaited, add: await sdk.auth.ready() before rendering user state
Tell me where you made changes after fixing.Problem 5: The login modal does not open, or closing it does not update the login state
Send the following to AI:
Please inspect my generator project for an Auth module login modal issue.
Project path: <your project path>
Check the following:
1. Check whether sdk.auth.login() is called to trigger the login modal
2. Check whether sdk.auth.onChange(callback) is used to listen for login state changes after the modal closes
3. If onChange is not set up, add a listener that refreshes the UI user state when the user logs in or out
4. Check whether the browser console shows any errors related to @makeblock/passport-client
For each item: report the current status and fix directly if there is a problem.Problem 6: Need to run code after login but don't know where to hook in
Send the following to AI:
Please inspect my generator project for the correct place to run code after login.
I want to run something automatically after the user logs in (for example, load cloud save data), but I'm not sure where to hook in.
Project path: <your project path>
Check the following:
1. Find where login state is handled in the project
2. Check whether sdk.auth.onChange(callback) is used — this is the correct way to receive a callback when login or logout happens
3. If it is not set up, add an onChange listener at the right location to run the desired operation when the user logs in
4. Note: onChange fires on both login and logout — check which state it is inside the callback before acting
Tell me where you made changes after fixing.Cloud Module
Problem 7: Calling sdk.cloud.save() throws an error or fails silently
Send the following to AI:
Please inspect my generator project for a Cloud module save failure.
Calling sdk.cloud.save() throws an error or fails silently.
Project path: <your project path>
Check the following:
1. Check the parameters passed to save() — the snapshot field must be a plain JSON-serializable object; it cannot contain functions, DOM elements, or circular references
2. Check the cover field — if provided, it must be a base64 data URL string, not a File object or Blob
3. Check whether the user is logged in — the Cloud module requires a login session; saving fails without one
4. Check the specific error message in the browser console and tell me what it says
For each item: report the current status and fix directly if there is a problem.Problem 8: Save succeeds but the cover image is blank
Send the following to AI:
Please inspect my generator project for a blank Cloud module cover image.
Cloud save succeeds but the saved record has no thumbnail (cover is blank).
Project path: <your project path>
Check the following:
1. Find where sdk.cloud.save() is called and check whether the cover field has a value
2. If cover is empty, check whether there is logic in the generator to capture a canvas screenshot and produce a base64 image
3. If canvas screenshot uses canvas.toDataURL(), check whether the canvas contains any cross-origin resources (images or fonts) — cross-origin resources taint the canvas and cause toDataURL to throw
4. If there is a cross-origin issue, check whether cross-origin resources are loaded with crossOrigin="anonymous" and whether the server returns the correct CORS headers
Tell me the findings, and fix any problems you find.Problem 9: sdk.cloud.restore(id) returns data but the canvas does not update
Send the following to AI:
Please inspect my generator project for a Cloud module restore issue.
sdk.cloud.restore(id) returns data successfully but the canvas does not update.
Project path: <your project path>
Check the following:
1. Find where sdk.cloud.restore() is called and check the returned data structure — the snapshot field in data.snapshot contains the original data passed during save
2. Check whether there is logic to apply the snapshot to the canvas after restore (for example, calling setState or applyState)
3. If not, add logic to apply the snapshot data to the canvas state after a successful restore
Tell me where you made changes after fixing.History Module
Problem 10: The history list is empty, but data has been saved
Send the following to AI:
Please inspect my generator project for a History module empty list issue.
sdk.history.getList() returns an empty array even though data has been saved.
Project path: <your project path>
Check the following:
1. Check whether the appKey used in SDK initialization matches the appKey used when the data was saved — history records are isolated by appKey
2. Check whether the user is logged in — history records are stored per user and cannot be retrieved without a login session
3. Check whether sdk.history.getList() is called after sdk.auth.ready()
4. Open the browser network panel, inspect the history list API request and response, and tell me what the response contains
Tell me the findings, and fix any problems you find.Problem 11: The total count in the history list is wrong
Send the following to AI:
Please inspect my generator project for a History module pagination issue.
The total field in the history list result does not match the actual number of records.
Project path: <your project path>
Check the following:
1. Find where the total field from sdk.history.getList() is used
2. Note: in the current SDK version, total equals the length of the returned array for the current page, not the true total count in the database
3. If the UI uses total to determine "whether more data exists" or "total page count", this logic will be inaccurate
4. Adjust the pagination logic: use "whether the returned count is less than pageSize" to determine whether more data is available
Tell me where you made changes after fixing.Credits Module
Problem 12: sdk.credits.getBalance() runs but the balance display never updates
Send the following to AI:
Please inspect my generator project for a Credits module balance display issue.
The credits balance does not update in real time, or does not refresh after a spend.
Project path: <your project path>
Check the following:
1. Check whether sdk.credits.onChange(callback) is used to listen for balance changes — after credits are consumed, the SDK automatically updates the balance and notifies through onChange
2. If onChange is not set up, add a listener that refreshes the credits display in the UI when the balance changes
3. Check whether sdk.credits.getBalance() is called at the right time (for example on page load) to fetch the latest balance
4. If a manual balance refresh is needed at a specific moment, call sdk.credits.getBalance() at that point
Tell me where you made changes after fixing.Problem 13: sdk.credits.consume() throws a permission error
Send the following to AI:
Please inspect my generator project for a Credits module consume permission error.
Calling sdk.credits.consume() throws a permission error or fails.
Project path: <your project path>
Check the following:
1. Check the action parameter passed to consume — the Credits consume endpoint requires the action to be registered in the platform console in advance; arbitrary strings are not allowed
2. Check whether this action has been applied for and registered in the platform console
3. If direct credits consumption is not needed, check whether sdk.billing should be used instead — the Billing module manages free quota and credits consumption together and is the better fit for most use cases
4. Open the browser network panel, find the consume request, check the specific error response, and tell me the error code
Tell me the findings and the recommended fix.Billing Module
Problem 14: sdk.billing.check() always returns insufficient balance, but the user has credits
Send the following to AI:
Please inspect my generator project for a Billing module check() returning incorrect results.
sdk.billing.check() returns insufficient balance even though the user has credits.
Project path: <your project path>
Check the following:
1. Check whether sdk.billing.getUsage() is called before check() — check() depends on cached data and getUsage() must be called first
2. Check whether getUsage() is called after the user logs in (the billing status cannot be retrieved correctly without a login session)
3. If getUsage() is missing, add await sdk.billing.getUsage() at the right location (after login or during initialization)
4. Confirm whether check() returns the correct result after the fix
Tell me where you made changes after fixing.Problem 15: withBilling wraps a function, but it fails even though the user has balance
Send the following to AI:
Please inspect my generator project for a withBilling usage issue.
withBilling(sdk.billing, action) fails even though the user has balance.
Project path: <your project path>
Check the following:
1. Find the withBilling call and check whether the parameters are correct:
first argument is the sdk.billing instance, second argument is the async function to execute
2. Check whether sdk.billing.getUsage() has been called before the withBilling call
3. Check the try/catch around withBilling — when balance is insufficient, it throws SdkError(40301); this error code must be caught separately to show the user a top-up prompt
4. Check the browser console for the specific error message and tell me what it says
For each item: report the current status and fix directly if there is a problem.Problem 16: Credits balance UI does not update after a billing consumption
Send the following to AI:
Please inspect my generator project for a credits refresh issue after Billing consumption.
After a billing consumption is triggered, the credits balance displayed in the UI does not update.
Project path: <your project path>
Check the following:
1. Check whether sdk.credits.onChange(callback) is used to listen for balance changes
2. The Billing module automatically refreshes credits after a successful consumption and notifies through credits.onChange
3. If credits.onChange is not set up, add a listener that updates the balance display in the UI when the balance changes
Tell me where you made changes after fixing.Export Module
Problem 17: Clicking the export or download button does nothing
Send the following to AI:
Please inspect my generator project for an Export module issue.
Clicking the export or download button has no effect.
Project path: <your project path>
Check the following:
1. Check whether sdk.export.register(provider) is called before sdk.export.download() to register the export provider
2. Check whether the provider object passed to register implements either getExportData or getExportCanvas (one of the two is required)
3. If neither method is implemented, help me implement a minimal getExportCanvas that retrieves an HTMLCanvasElement from the canvas element and returns it
4. Check the browser console for related errors
For each item: report the current status and fix directly if there is a problem.Problem 18: Exporting SVG format throws an error
Send the following to AI:
Please inspect my generator project for an Export module SVG export error.
Exporting in SVG format throws an error, but PNG works fine.
Project path: <your project path>
Check the following:
1. Check whether the export provider implements getExportData — SVG export requires getExportData; getExportCanvas cannot be used for SVG
2. If only getExportCanvas is implemented, converting from canvas to SVG will fail — getExportData must be implemented and return { type: 'svg', svgString: '<svg>...</svg>' } when the type is svg
3. If the generator's rendering engine can produce an SVG string, help me implement getExportData to support SVG export
Tell me where you made changes after fixing.Problem 19: Export has no billing gate — any user can export for free
Send the following to AI:
Please inspect my generator project for a missing billing gate on the Export module.
All users can currently export without any credits or quota limit.
Project path: <your project path>
Check the following:
1. Check whether there is a billing check before sdk.export.download() or sdk.export.openInStudio()
2. The Export module does not include billing logic — it must be combined with withBilling:
wrap the export call with withBilling(sdk.billing, async () => { sdk.export.download() })
3. If billing is not integrated, help me wrap the export action with withBilling to enforce the "must have balance to export" logic
Tell me where you made changes after fixing.Template Module
Problem 20: sdk.template.applyToRuntime() runs but the canvas does not change
Send the following to AI:
Please inspect my generator project for a Template module applyToRuntime issue.
Calling sdk.template.applyToRuntime(templateData, runtime) does not update the canvas.
Project path: <your project path>
Check the following:
1. Check whether the runtime object passed to applyToRuntime implements a setState method
2. applyToRuntime calls runtime.setState(snapshot) internally — if the runtime object does not have this method, the template cannot be applied
3. Check the setState implementation — it should accept template data and update the canvas state
4. If the runtime object is missing setState, add an implementation of that method
Tell me where you made changes after fixing.Problem 21: Not sure which PanelSchema fields should go into the template data
Send the following to AI:
Please help me determine which fields in this generator project should be included in template data.
I am not sure which fields from the PanelSchema should be the adjustable template parameters.
Project path: <your project path>
Check the following:
1. Find the PanelSchema definition in the generator (usually in getPanelSchema() or a similar method)
2. sdk.template.getFieldOptions(panelSchema) can extract the list of eligible fields from a PanelSchema
3. Check the current template data builder for the adjustableFields and panelFilter fields — these control which parameters the user can adjust during Customize
4. Tell me what fields the current PanelSchema contains and help me determine which should be adjustable template fields
Output the recommended adjustableFields and panelFilter configuration.Full Scan
If you are not sure which module is causing the problem, ask AI to run a full scan:
Please run a full SDK integration audit on this generator project.
Project path: <your project path>
Check each module below and output a status table:
**Initialization**
- GeneratorSDK.init is called with a valid appKey
- env parameter matches the runtime environment
- Initialization runs before all other SDK calls
**Auth Module**
- sdk.auth.ready() is awaited during page initialization
- sdk.auth.onChange is used to listen for login state changes
**Cloud Module**
- sdk.cloud.save() snapshot is JSON-serializable
- cover image is implemented
- sdk.cloud.restore() data is applied to the canvas
**History Module**
- getList is called after login
- total field is not used for true pagination (it equals the current page array length)
**Credits Module**
- sdk.credits.onChange is used to listen for balance changes
**Billing Module**
- getUsage() is called before check()
- withBilling correctly handles insufficient balance (SdkError 40301)
**Export Module**
- sdk.export.register(provider) is called to register the export provider
- SVG export is implemented via getExportData
- Export is wrapped with billing gate
**Template Module**
- applyToRuntime runtime object implements setState
Output format:
| Module | Check Item | Status | Notes |
|--------|------------|--------|-------|
Status key: ✅ implemented · ❌ missing · ⚠️ partial
For every ❌ and ⚠️ item, fix it and then output the status table again.Related Pages
- SDK Overview — module capabilities and integration order
- SDK Initialization — GeneratorSDK.init parameters and environment config
- Authentication — Auth module and token behavior
- Debugging Guide — how to inspect SDK network requests and module state