A shared client for PayPal/Braintree client sdk modules. Has both client-side and server-side bindings to help you build and integrate an sdk component.
Your client-side sdk component can take advantage of any common utilities or functionality exposed by this module. For example:
- Determining the current paypal url
- Getting the merchant's client-id
- Running experiments.
import { getClientID } from '@paypal/sdk-client/src';
fetch('https://api.paypal.com/v1/foo', {
headers: {
'client-id': getClientID()
}
});This module helps you load the payments sdk in a child window, matching the url from the parent.
- You're building a component that is rendered into an iframe or popup window.
- Your component uses zoid to construct the component, and to communicate between the component and the parent page and vice-versa.
- You want to make sure the version of the component between the parent and child, to prevent any incompatibilities in the messaging protocol zoid defines (trust me on this one)
- You also want to take advantage of browser caching benefits, and not download dependencies like zoid multiple times in each new frame or window being rendered
- You can't just load
<script src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID"></script>in the child frame or popup, because different query params could have been passed on the top level page, and to take advantage of any caching benefits you need to match the url exactly as it appeared in the parent. - You also probably want to avoid passing down all of the query params from
/sdk/js, but that's a lot to keep track of, and you would need to update your code every time a new parameter is added. - Or, you could pass the entire
https://www.paypal.com/sdk/js?client-id=xyz&...url down from the parent to each new child; meaning we'll get an exact match each time, with exact the same version of the code, and any new url params will automatically be included without any more integration work. - And of course, if we're doing that, we need to validate the url before we throw it into a script tag, to prevent xss or injection attacks
This module helps with that.
- Import
unpackSDKMeta:
import { unpackSDKMeta } from '@paypal/sdk-client';- Call
unpackSDKMetawithreq.query.sdkMeta, passed from the client in the query string, and pass the script tag in the page render.
// Listen for requests to your app
app.get('/my-app', (req, res) => {
// Unpack the sdk meta payload from the client
const { getSDKLoader } = unpackSDKMeta(req.query.sdkMeta);
// Call getSDKLoader to build a script tag, passing in csp nonce, if applicable
const sdkScriptTag = getSDKLoader({ nonce });
// Insert script tag into response
res.send(`
<body>
<h1>My App</h1>
${ sdkScriptTag }
</body>
`);
})- Ensure the
sdkMetapayload is passed to the child window from the parent. If you are using zoid to construct your component, please add the following:
import { getSdkMeta } from '@paypal/sdk-client/src';
let MyComponent = zoid.create({
tag: 'my-component',
url: 'https://www.paypal.com/my-component',
props: {
sdkMeta: {
type: 'string',
value: getSdkMeta,
queryParam: true
}
}
})If you are not using zoid, please use getSdkMeta() to construct the sdkMeta payload, and pass it to your child-window or frame in a different way.
Notes:
- The script tag should not introduce any extra latency. It has already been downloaded, pre-cached, and pre-parsed in the parent window. So it is usually safe to put in the
<head>tag. - Assuming a zoid component integration,
window.xprops, containing the props used to receive data from the parent and used to send callbacks back to the parent window, will only be available after the script tag has completed loading on the client. If any other scripts requirewindow.xpropsimmediately, please ensure the sdk script tag is placed before those scripts. unpackSDKMetawill throw an error ifreq.query.sdkMetadoes not validate. This should be handled and translated into a 500 server error, indicating that the payload has been tampered with.unpackSDKMetamay be passedundefinedifreq.query.sdkMetais not present. This is necessary for some legacy integrations where the sdk metadata is passed viawindow.nameentirely on the client-side.
npm install --save @paypal/sdk-client- Fork the module
- Run setup:
npm run setup - Start editing code in
./srcand writing tests in./tests npm run build
npm run build-
Edit tests in
./test/tests -
Run the tests:
npm test