search

adobe / adobe-client-data-layer

An event-driven store for all trackable data of your site.
Apache License 2.0
115 stars 27 forks source link

Improve installation instructions #129

Open Aaronius opened 3 years ago

Aaronius commented 3 years ago

This isn't a bug, but rather some feedback on how to improve the installation instructions.

The Consuming section (https://github.com/adobe/adobe-client-data-layer#consuming) of the readme is confusing to me and a couple people on my team. I’ll try to explain why.

The first thing it says is to install the data layer using npm. In my experience, the reason I would npm install a dependency is typically so I can import the dependency in my app’s modules. Rather than showing me how to import it as a dependency, though, it says to locate the dist folder and then add <script src="adobe-client-data-layer.min.js" async defer></script> to my HTML. The term “locate” doesn’t mean much, other than confirming I can see a dist directory within the @adobe/adobe-client-data-layer directory. Okay, fair enough, I can see the directory.

Adding <script src="adobe-client-data-layer.min.js" async defer></script> to my HTML is insufficient, because it’s going to be referencing a adobe-client-data-layer.min.js that’s supposed to be in the same directory as the HTML file, not from the node_modules/@adobe/adobe-client-data-layer directory. I would probably need to set up some sort of build script to move adobe-client-data-layer.min.js from the package directory to my web-server-hosted directory, but there’s no mention of this.

At the end, there’s a note about directly accessing the minified version of the data layer without downloading the sources and compiling them. Did I ever have to download the sources? Oh, you mean when I installed the package as a dependency, I assume. Did I ever have to compile the sources? I don’t think so. And what does “directly accessing” them mean? You mean I can download them and self-host them or do you mean I could reference that URL directly from my script tag? Those both seem a lot easier than installing the npm package, creating a build step, etc., but, if so, why wasn’t this listed as the first thing to try? What are the downsides? Is this URL referencing a CDN I might be able to trust? Is it Adobe’s?

I’m still left wondering whether I can import the data layer into my ES6 or CommonJS module. Is that possible? If so, how?

Anyway, I can personally figure out the answer to some of those questions on my own, but there are a lot of customers who won’t, and will struggle getting it set up.

My suggestion would be that we put the built files on an Adobe-managed Akamai account (similar to what we do for the web SDK, Launch libraries, etc.) and then tell customers to put a script tag on their page with a URL to that Akamai-hosted file. Then, briefly mention that they can download the file and self-host it if they would like more control.

Beyond that, if there’s a way to actually install the data layer and import it as a module, that would be nice to know about, but that would come later in the page for more advanced customers.

Something more along the lines of this may be helpful: https://experienceleague.adobe.com/docs/experience-platform/edge/fundamentals/installing-the-sdk.html?lang=en

johnstew commented 1 year ago

Agree with @Aaronius that it'd be great if there was some clarity around the use cases listed in his issue comment. Since this is the data layer is an array that we instantiate and this module expects it to exist. I feel like we should able to npm install and simply import it anywhere in our application and it should look for the data layer and begin doing its thing from anywhere.

If this isn't preferred then I think being explicit about the fact that we will have to create some sort of process around self hosting the library would be useful with some recommended approaches would go a long way.