Aplikacja Meta - konfiguracja
Jak przygotować własną aplikację Meta, Użytkownika Systemowego i token dostępu dla OWLI - przypadki użycia, uprawnienia tokenu (także pod Instagram) i najczęstsze błędy.
- Czym jest aplikacja Meta i po co OWLI jej potrzebuje
- Kluczowe pojęcia
- Trzy warstwy, które muszą się zgadzać
- Jak wygląda proces
- Przypadki użycia w aplikacji
- Uprawnienia tokenu
- Instagram - co jeszcze musi być połączone
- Nowy token - jak go podmienić w OWLI
- Jak sprawdzić, że działa
- Pełna instrukcja ze zrzutami ekranu
- Najczęstsze problemy
- Masz token? Wracaj do instalacji
Czym jest aplikacja Meta i po co OWLI jej potrzebuje
OWLI łączy się z Meta przez Twoją własną aplikację deweloperską, a nie przez wspólne konto. To ważne: dzięki temu Ty jesteś właścicielem połączenia, a każda operacja na koncie reklamowym idzie przez Twój token dostępu, na Twoich uprawnieniach. Nikt nie siedzi po środku.
Dla agencji to jedna aplikacja, która obsługuje wszystkich klientów - do jednego Użytkownika Systemowego przypisujesz kolejne konta reklamowe i OWLI pracuje na każdym z nich.
To jednorazowa konfiguracja. Robisz ją raz, a efektem jest token (ciąg zaczynający się od EAA...), który wklejasz podczas instalacji OWLI. Później już tylko korzystasz - token działa w tle.
Co przygotujesz
- Aplikacja Meta - łączy OWLI z Twoimi kontami reklamowymi. Tworzysz ją w panelu Meta Developers (developers.facebook.com).
- Użytkownik Systemowy - konto techniczne w Twoim Portfolio Firmowym. Przez nie OWLI wykonuje operacje na kontach klientów.
- Token dostępu (
EAA...) - klucz, który wklejasz podczas instalacji OWLI. Generujesz go przy Użytkowniku Systemowym.
Cała konfiguracja zajmuje zwykle 15-20 minut. Robisz ją raz.
Wymagane jest Portfolio Firmowe Meta
To standardowe narzędzie pracy, w którym przypisuje się konta reklamowe i inne zasoby firmowe. Tam też tworzy się Użytkownika Systemowego wraz z tokenem dostępu.
Kluczowe pojęcia
Zanim przejdziesz przez kroki, warto rozumieć, co jest czym. Te nazwy pojawią się w panelu Meta:
- Portfolio Firmowe (Business Portfolio, dawniej Menedżer Firmy) - Twoja przestrzeń w Meta, w której trzymasz konta reklamowe, strony i pixele. To tu mieszka aplikacja i Użytkownik Systemowy.
- Aplikacja Meta - "wtyczka", przez którą program taki jak OWLI dostaje prawo rozmowy z Meta. Tworzysz ją w Meta Developers.
- Przypadek użycia (use case) - pakiet możliwości, który dodajesz do aplikacji, np. „tworzenie reklam" albo „zawartość na Instagramie". Od przypadków użycia zależy, jakie uprawnienia aplikacja w ogóle może dać tokenowi.
- Marketing API - interfejs Meta do tworzenia i zarządzania reklamami. To jego OWLI używa, żeby czytać wyniki i zmieniać kampanie.
- Catalog API - interfejs do produktów i katalogów (przydatny przy reklamach produktowych).
- Użytkownik Systemowy (System User) - "robot-pracownik" w Twoim Portfolio. Nie jest osobą, nie loguje się hasłem - działa przez token. To on ma dostęp do kont klientów.
- Token dostępu (
EAA...) - klucz, który udowadnia Meta, że to Ty. Wklejasz go raz, przy instalacji.
Dlaczego akurat tak
Meta celowo oddziela kto (Użytkownik Systemowy) od czym (aplikacja) i do czego (konkretne konta reklamowe). Dzięki temu możesz dać OWLI dostęp tylko do wybranych kont, a nie do całego Portfolio - i w każdej chwili ten dostęp odebrać.
Trzy warstwy, które muszą się zgadzać
Większość problemów z połączeniem bierze się z tego, że jedna z trzech warstw nie pasuje do pozostałych:
| Warstwa | Gdzie to ustawiasz | Co decyduje |
|---|---|---|
| Aplikacja | developers.facebook.com, przypadki użycia aplikacji | jakie uprawnienia w ogóle da się nadać |
| Token | Portfolio Firmowe, Użytkownik Systemowy, „Wygeneruj token" | które uprawnienia ma ten konkretny token |
| Zasoby | Portfolio Firmowe, Użytkownik Systemowy, przypisane zasoby | do czego token ma dostęp: konta reklamowe, strony, konto Instagram, katalogi, piksele |
Token ma tylko to, co zaznaczysz przy generowaniu
Uprawnienie da się zaznaczyć przy tokenie tylko wtedy, gdy ma je aplikacja. A dodanie uprawnienia w aplikacji nie zmienia tokenu, który już masz. Po każdej zmianie w aplikacji wygeneruj nowy token i zapisz go w OWLI.
Jak wygląda proces
Pięć kroków. Poniżej skrót z krótkim "po co" przy każdym - pełny przewodnik ze zrzutami ekranu jest w PDF (patrz niżej).
- Załóż konto na developers.facebook.com - zaloguj się tym samym Facebookiem, na którym masz konto reklamowe. Inaczej aplikacja nie zobaczy Twoich kont.
- Utwórz aplikację i dodaj przypadki użycia - przypisz aplikację do Portfolio Firmowego i dodaj przypadki użycia z listy niżej. To decyduje, co OWLI będzie umiał.
- Opublikuj aplikację - uzupełnij link do polityki prywatności, dodaj ikonę (500x500 pikseli) i kliknij „Publish". Bez publikacji aplikacja nie zadziała - to najczęściej pomijany krok.
- Utwórz Użytkownika Systemowego - w Portfolio Firmowym dodaj nowego z rolą Admin i przypisz mu aplikację oraz zasoby, które chcesz obsługiwać: konta reklamowe, strony, konto Instagram, katalogi i piksele. Tu decydujesz, do czego OWLI ma dostęp.
- Wygeneruj token - przy Użytkowniku Systemowym kliknij „Wygeneruj token", wybierz aplikację, zaznacz uprawnienia z listy niżej i zatwierdź. Zapisz ciąg
EAA...w bezpiecznym miejscu. To Twój klucz do instalacji.
Przypadki użycia w aplikacji
W panelu aplikacji (developers.facebook.com) dodaj te przypadki użycia:
- Twórz reklamy i zarządzaj nimi za pomocą API marketingu - kampanie, zestawy reklam, reklamy, piksele.
- Zmierz dane skuteczności reklamy za pomocą API marketingu - wyniki i statystyki.
- Zarządzaj produktami za pomocą API katalogu - katalogi i reklamy dynamiczne.
- Zarządzaj wiadomościami i zawartością na Instagramie (Manage messaging & content on Instagram) - tylko jeśli OWLI ma pracować z postami z Instagrama. Znajdziesz go w oknie „Add use cases", w kategorii zarządzania treściami. W tym przypadku dodaj uprawnienie
instagram_basicprzyciskiem Add.
Status „Ready for testing" przy uprawnieniu wystarcza, gdy pracujesz na kontach z własnego Portfolio.
Uprawnienia tokenu
Przy generowaniu tokenu zaznacz:
| Uprawnienie | Do czego w OWLI | Wymagane |
|---|---|---|
ads_management | tworzenie i zmiany kampanii, piksele | tak |
ads_read | wyniki i struktura kont | tak |
business_management | lista kont w Portfolio, nadawanie dostępów | tak |
pages_show_list | lista stron | tak |
pages_read_engagement | odczyt stron i postów, promowanie postów | tak |
pages_manage_ads | reklamy w imieniu strony | tak |
pages_manage_metadata | nadawanie dostępu do strony Użytkownikowi Systemowemu | tak |
catalog_management | katalogi, reklamy dynamiczne | tak |
instagram_basic | przeglądanie postów z Instagrama, promowanie posta z IG po linku, masowe promowanie postów (Promowanie postów) | opcjonalne |
Jeśli któregoś uprawnienia nie ma na liście przy generowaniu tokenu, znaczy to, że nie ma go aplikacja. Dodaj je w przypadkach użycia aplikacji, np. pages_manage_ads dodasz przyciskiem Add w przypadku tworzenia reklam. Potem wygeneruj token jeszcze raz.
Bez instagram_basic
OWLI działa normalnie na kampaniach, ale nie przejrzy postów z Instagrama i nie wypromuje posta z IG po linku. Uprawnienie możesz dodać później - wtedy wygeneruj nowy token. Dotyczy to też masowego promowania postów z Instagrama.
Instagram - co jeszcze musi być połączone
Samo instagram_basic nie wystarczy. Żeby OWLI widział posty z Instagrama, konto IG musi być:
- firmowe albo twórcy - konto prywatne nie udostępnia postów,
- połączone ze stroną na Facebooku,
- podłączone do konta reklamowego w Portfolio Firmowym,
- przypisane Użytkownikowi Systemowemu (krok 4).
Przy postach OWLI widzi liczbę polubień i komentarzy. Treści komentarzy nie czyta.
Szczegóły po stronie Meta: Use Posts as Instagram Ads oraz IG User Media.
Nowy token - jak go podmienić w OWLI
Gdy zmieniasz uprawnienia albo token wygasł, nowy token zapisujesz w zwykłym terminalu (nie w oknie Claude Code), w folderze owli, komendą npm run owli -- env set meta. Wklej token w ukryte pole - nie pojawi się na ekranie, to celowe. OWLI sprawdzi go w Meta przed zapisem. Potem uruchom Claude Code ponownie.
Jeśli OWLI masz na kilku komputerach, zapisz nowy token na każdym z nich.
Jak sprawdzić, że działa
Stan kluczy pokaże npm run owli -- env list (bez wartości, tylko końcówka). Potem wystarczy jeden odczyt - poproś OWLI o kilka postów:
› Pokaż 5 ostatnich postów z Instagrama klienta Sklep BOWLI: Mam 5 postów z Instagrama Sklep B, z liczbą polubień i komentarzy przy każdym.
Jeden odczyt wystarczy. Nie testuj na wszystkich kampaniach po kolei - limit operacji aplikacji Meta jest wspólny dla wszystkich Twoich klientów.
Pełna instrukcja ze zrzutami ekranu
Ten wpis daje Ci mapę i pojęcia - wystarczy, żeby zrozumieć proces i zacząć. Dokładny przewodnik ekran po ekranie (20 stron w PDF, z każdym kliknięciem pokazanym na zrzucie) jest osobno:
- Masz OWLI? Instrukcja przyszła mailem po zakupie. Sprawdź skrzynkę, także folder spam.
- Jeszcze nie masz OWLI? Pobierz ją za darmo na stronie Instrukcja Meta.
Jeśli utkniesz na którymś kroku albo panel Meta wygląda inaczej niż się spodziewasz - sięgnij po PDF. Tam każdy ekran jest pokazany, z zaznaczonym miejscem do kliknięcia.
Najczęstsze problemy
„Nie mam uprawnień do przypisania konta" - Twój token musi być administratorem w Portfolio Firmowym z zaawansowanym dostępem. OWLI nie nada sobie uprawnień sam - jeśli ich brakuje, pokaże instrukcję ręcznego przypisania zasobu (konto reklamowe, strona, pixel).
„Aplikacja nie działa / Meta odrzuca token" - najczęściej to brak publikacji aplikacji (krok 3) albo logowanie na innym Facebooku niż ten z kontem reklamowym (krok 1).
`(#10) Application does not have permission` - aplikacji albo tokenowi brakuje uprawnienia. Sprawdź przypadki użycia w aplikacji, potem wygeneruj nowy token z tym uprawnieniem i zapisz go w OWLI.
Kod 100, podkod 33: „does not exist, cannot be loaded due to missing permissions" - token nie widzi obiektu. Zwykle zasób nie jest przypisany Użytkownikowi Systemowemu albo konto Instagram nie jest podłączone do konta reklamowego.
„Dodałem uprawnienie, a nic się nie zmieniło" - stary token go nie dostanie. Wygeneruj nowy i zapisz go w OWLI.
„Mało operacji, API się blokuje" - nowa aplikacja ma niski limit operacji. Żeby go podnieść, wykonaj przez jakiś czas około 500 operacji i przejdź recenzję w Meta. To normalne i jednorazowe. Szczegóły opisuje rozdział 4 pełnego PDF.
„Mam kilku klientów" - nie zakładasz osobnej aplikacji na każdego. Do jednego Użytkownika Systemowego przypisujesz kolejne konta reklamowe (krok 4) i jeden token obsługuje wszystkich.
Masz token? Wracaj do instalacji
Token (EAA...) wklejasz w jednym z kroków instalatora OWLI - kreator sprawdza go na żywo i od razu powie, czy Meta go akceptuje. Token można też pominąć i dodać później.
Przejdź do wpisu Instalacja OWLI i wklej token w kroku, w którym kreator o niego poprosi.
W skrócie
Aplikacja z przypadkami użycia → Użytkownik Systemowy z przypisanymi zasobami → token EAA... z zaznaczonymi uprawnieniami → wklejasz przy instalacji. Zmieniasz uprawnienia? Nowy token i npm run owli -- env set meta. Pełne kroki ze zrzutami są w PDF (mailem po zakupie) oraz na stronie Instrukcja Meta.